Agilent E6966B IMS-SIP Network Emulator Software Help

Welcome to the Agilent E6966B
IMS-SIP Network Emulator Software Help

This help describes how to use the IMS-SIP Software for revision 8.x

Last Updated: 2014-06-02

Notices

The Agilent E6966B IMS-SIP Network Emulator Software (IMS-SIP Software) enables you to test end user applications (voice, video, SMS) provided over an IP infrastructure using an IMS architecture. This capability is helpful in testing a UE's functionality as well as demonstrating its capabilities. Both the server and client are PC based software. The IMS-SIP client/server pair enables you to demonstrate applications and perform the End-to-End (E2E) application test. Note that to support an E2E application, the IMS-SIP client and server can be used with a mobile phone under test with an embedded IMS client, or alternatively it can be used with a second Agilent IMS-SIP client.

The purpose of this help file is to assist you in using the IMS-SIP Software. For installation instructions, please refer to the manual located here:

http://cp.literature.agilent.com/litweb/pdf/E6966-90002.pdf.

Additional application information, links to configuration files, and other E6966B related software and files are periodically updated and can be found here: Additional Information.

The IMS-SIP Software help is organized into the following sections:

  • Getting Started

  • Licensing

  • Server User Interface

  • Client User Interface

  • Server API Reference

  • Client API Reference

  • Troubleshooting

© 2014 Agilent Technologies, Inc.


E6966B IMS-SIP Network Emulator Software

Getting Started

Last Updated: 2014-06-02

This topic provides information on getting started using the Agilent Technologies E6966B IMS-SIP Emulator Software including:

  • System Requirements

  • Installation

  • Licensing

  • Server First Steps

  • Client First Steps

System Requirements

Server and Client PC Requirements

An IBM® (or compatible) PC with at least:

  • Processor: 2.0 GHz Pentium 4® or equivalent

  • Operating System: Microsoft® Windows® XP Professional Service Pack 3 (English version only) or Windows 7 Professional

  • Memory: 2 GB RAM

  • Hard Disk Space: 2 GB of available hard disk space

  • Connection: IP Network Connection (broadband, LAN, and wireless)

  • LAN Port (If you are using LAN for your connection.)

  • Sound Card: Full-duplex, 16-bit

  • 2 USB ports: (2.0 or later)

Both the E6966B Server and Client software can be installed on the same PC, however in this situation, use only the E6966B-1FP (server license) to activate BOTH products. See Licensing Use Cases for more information.

Other Requirements

  • Microsoft Internet Explorer® version 6.0 or later

  • E6966B-1FP IMS-SIP Server Emulator fixed, perpetual license (To obtain your license, follow the instructions on the Software Entitlement Certificate you received upon ordering the software.) See Licensing for more information.

  • E6966B-2FP IMS-SIP Client Emulator fixed, perpetual license (To obtain your license, follow the instructions on the Software Entitlement Certificate you received upon ordering the software.) See Licensing for more information.

  • E6966B-1FP IMS-SIP Server Emulator Software (You will need access to the web at: www.agilent.com/find/E6966B).

  • E6966B-2FP IMS-SIP Client Emulator Software (You will need access to the web at: www.agilent.com/find/E6966B).

Installation

This section assumes that you have acquired all the items listed under System Requirements, above.

Close any applications currently running before installing the software.

For complete installation instructions, please refer to the manual located here:

http://cp.literature.agilent.com/litweb/pdf/E6966-90001.pdf.

Licensing

Refer to Licensing.

Server First Steps

  1. Select File > Configuration to configure the appropriate network interface you wish to use.
  2. In the same view, setup the Realm/domain name to associate with the IMS-Server.

Client First Steps

  1. Use the Configuration tab to set the following parameters:

    • Speaker and microphone devices to use during VoIP calling (and associated volume levels)

    • The codec sets for Audio and Video transfer during a VoIP call

    • File Locations used when sending test audio and video files, or when recording received audio

    • The following Connection parameters for registering the client with the server:

      • Client and server IP addresses and port numbers (note that multiple instances of the client must be configured with different contact IP port numbers)

      • The Transport type associated with SIP signaling-plane messaging between the client and IMS Server application

      • The User name, Display name, and Domain associated with the registration of the client

      • The Expire time (Ensure that this time-out is greater than 0.)

  2. Register the client with the server by performing either of the following:

    • Selecting the Register button on the Main Menu toolbar at the top of the application

  3. If there is a problem registering, see Registration Problems in the Troubleshooting section.


Licensing

Licensing the IMS-SIP Software

Last Updated: 2014-06-02

This topic provides information on licensing the E6966B IMS-SIP Software including:

  • Licensing_Options

  • Licensing_Use_Cases_

Licensing Options

The E6966B IMS-SIP Software must be licensed in order to be activated.

Follow the instructions on the “License Entitlement Certificate” that you received when you purchased the E6966B-1FP (Server Emulator) alone or in conjunction with the E6966B-2FP (Client Emulator). These instructions enable you to redeem your license keys for these products. See Figure 1 and Figure 2 below.

          1.

    1. The E6966B-1FP (fixed) or E6966B-1TP (transportable) server license allows a single instance of the server emulator software and multiple instances of the client emulator software to operate on a single host PC (see Figure 1 and Figure 2 below).

    2. The E6966B-2FP (fixed) or E6966B-2TP (transportable) client license allows multiple instances of the client emulator software to run on the client PC (see Figure 1 below)

    3. The E6966B-3FP (fixed) or E6966B-3TP (transportable) conference-server license allows a single instance of the conference-server emulator to run on a single host PC.

    *** DO NOT install E6966B-1FP and E6966B-2FP licenses on the same PC. ***

Licensing Use Cases

There are two licensing use cases for the E6966B:

  1. E6966B testing a UE with no embedded SIP client. See Figure 1 below.

  2. E6966B testing a UE with embedded SIP client. See Figure 2 below.

To perform E2E VoIP, Audio, or Video tests, you must install at least one instance of the client emulator software on a separate pc from the one on which you have installed the server emulator software. Only the "Send SMS" E2E test can be performed when both the client and the server emulator software are on the same pc.

Determine the scenario you need and implement the licensing as shown.

Figure 1: Testing UE Without Embedded SIP Client

Figure 2: Testing UE with Embedded SIP Client


Server User Interface

Server User Interface (UI)

Last Updated: 2014-06-02

The IMS-SIP Server Emulator Software is a software application designed to run in conjunction with at least one client for the purposes of testing and demonstrating a UE's ability to perform VoIP, Video, and SMS/MMS over an IP infrastructure using IMS architecture. To support End-to-End (E2E) application testing, two clients and one server are required.

For more information on using the server, refer to the following topics:

  • Overview

  • Configure

  • Subscriber Data

  • Message

  • Control


Overview-Server UI

Overview: Server User Interface (UI)

Last Updated: 2014-06-02

The IMS-SIP Server Emulator Software UI can be divided into the following seven areas shown in the figure below:

  1. Main_Menu

  2. Setup

  3. Registered_Users

  4. Subscribers

  5. Logging_Control

  6. Diagnostics

  7. Status_Bar

1 Main Menu

File - This drop-down menu contains the following options:

  • Load Configuration- Enables you to load a configuration previously saved in your data file folder.

  • Load - Enables you to load a saved configuration from your data file folder.

  • Recent - Enables you to load a recently used saved configuration in your data file folder.

  • Save Configuration- Saves your current configuration to your data file folder.

  • Exit - Contains the option to exit the program.

Configuration - This drop-down menu contains the following options:

  • General Configuration - Enables you to set parameters required to set up the server. See General Configuration for detailed information.

  • Custom SIP Error Responses – Enables you to specify custom error-response message content which can be utilized (in conjunction with control-plane filtering) to configure the server to generate custom SIP response content, in response to specific incoming requests. See Custom SIP Error Responses for detailed information.

  • Filtering Configuration – Enables you to specify to modify the control-plane and user-plane filtering applied by the server. See User-Plane API Filtering-Rule Specification for detailed information. Control-plane filtering is further described in Control-Plane API Filtering-Rule Specification. User-plane filtering is further described in User-Plane Filtering Overview. Control-plane filtering is further described in Control-Plane Filtering Overview.

  • Message Accounts – Enables you to configure and modify message-accounts associated with testing the Message-Waiting-Indication (MWI) service functionality. See Message Accounts for detailed information. For more information on creating message accounts, refer to Using_Message_Accounts.

  • Subscriber Data – Enables you to configure subscriber-specific profiles. For example supplementary-service and security profiles can be specified and configured on a per-user/subscriber basis using this category. When a user registers to the IMS server, the user-specific subscriber profile is downloaded/cached and associated with the user. If no specific profile exists for the identity of the registered-user, the “default” profile is associated with the registering user. See Subscriber Data for detailed information.

Help - This drop-down menu contains the following options:

  • Help - Opens the help file.

  • About - Opens a window for the E6966B that contains information such as the revision number.

2 Setup

This area has two tabs, which provide the primary interaction with the IMS-SIP Server Emulator software.

  • Message - enables you to configure, create, and send an SMS message to the client(s).

  • Control - enables you to perform various server-initiated actions on a selected client.

3 Registered Users

This area displays all currently registered clients.

4 Subscribers

This area displays all subscribers.

5 Logging Control

This area enables you to control the logging features provided by the application.

6 Diagnostics

This area displays diagnostic and logging information, such as call-flow logging.

7 Status Bar

The status bar located at the bottom of the IMS-SIP Server Emulator Software enables you to quickly verify several things including:

  • Call Flow Logging

  • WCF Port

  • Server Port

  • Domain


Configuration

Last Updated: 2014-06-02

Configuration, from the main menu area of the Server UI, enables you to configure the server in the following categories:

  • General Configuration

  • Custom SIP Error Responses

  • Filtering Configuration

  • Message Accounts

  • Subscriber Data


General Configuration

Last Updated: 2014-06-02

Selecting Configuration > General Configuration from the main menu area of the Server UI enables you to configure the following functions:

  • Connection

  • Registration

  • SIP Signaling Control

  • Miscellaneous

  • Logging

Connection

Transmission Network Interface - This setting enables you to configure the network interface over which you intend to test IMS-SIP Signaling between Server and Clients. In particular, this adapter setting is used in cases where communication between client and server use link local addressing.

For example, in the case of IPv6 link-local addressing, a scope/zone identifier is necessary to determine which network adapter transmits the IPv6 datagram. The Transmission Network Interface setting provides the information to enable a resolution, preventing a conflict when deciding which adapter to use when sending outgoing transmissions.

Reception IP Addresses - Enables you to select/deselect the local IP Addresses used by the server for the reception of SIP/IMS signaling.

SIP Port - Enables specification of the server-side listening SIP Port on which SIP/IMS signaling is received.

WCF Port - Enables specification of the server-side listening WCF Port over which .NET-based WCF remote-control is performed.

Restart WCF - An immediate action allowing a close or re-open of the WCF network socket/port defined by the WCF Port setting.

Registration

Realm/Domain - Specifies the realm/domain controlled by the server. For example: agilent.com or test.3gpp.com.

    • When IMS clients send requests to the Server, if the host is not explicitly provided (for example when a UE is using TEL URIs), and the target domain cannot otherwise be determined from the SIP message alone, this parameter is used to resolve the targeted domain.

    • This parameter also specifies the realm parameter applied to authentication procedures.

Max-Expires - Specifies the server-capped maximum Expires value. If a REGISTER is received which includes an Expires value which exceeds this value, the incoming value is capped to the Server-defined maximum as per RFC 3261.

SIP Signaling Control

Include Record-Route in INVITE - Specifies whether the Server includes itself in an appended Record-Route header in any INVITEs forwarded via the Server (thereby ensuring any subsequent in-dialog signaling is guaranteed to be routed via the Server, and not just directly peer-to-peer).

Include Server-initiated 180-RINGING (Initial INVITE) - Specifies whether the server provides a 180 RINGING provisional response to received INVITE requests that perform an initial session-establishment procedure.

Send over-sized SIP Requests via TCP - Specifies whether to enforce forwarding/proxying a SIP Request over TCP transport when the intended target is nominally utilizing a UDP transport and the SIP Request is oversized with respect to the UDP MTU criteria outlined in [RFC 3261].

If this setting is disabled, the server always uses the nominal protocol-type of the intended target (regardless of whether the Request is oversized), whereby the nominal type is generally dictated by the transport-type indicated by the target during registration to the server.

Note: For the disabled case, this implies that, for UDP transport, oversized messages undergo UDP fragmentation during forwarding or proxying.

Miscellaneous

E.911 Configuration - Provides access to various emergency sessions/E.911 parameters.

SMSC Config - Provides access to parameters associated with the Short-Messsage Service Centre (SMSC).

Logging

Enable debug log - Turns on debug logging tool. This setting should generally be disabled, and is only intended for capturing additional diagnostic information when reporting application issues to Agilent.

Configure call flow log colors - Enables you to set the color of the displayed call flow for the following parameters:

Font Color - This color setting enables you to configure the font color associated with logged message entries in the Call Flow Diagram.

To Server - This color setting enables you to configure the background color associated with logged message lines in the CFD which are targeted at the server.

From Server - This color setting enables you to configure the background color associated with logged message lines in the CFD which originate from the server.


Custom SIP Error Responses

Last Updated: 2014-06-02

Selecting Configuration > Custom SIP Error Responses from the main menu area of the Server UI enables you to modify (add, remove, edit, or copy) custom SIP message-content entries. In addition, you can load or save the custom-message configuration to a file.

For additional information on creating Custom SIP Error Responses, refer to How to Create Custom Error Responses and Control-Plane Filtering Overview.

See Also

How to Create Custom Error Responses

Control-Plane Filtering Overview


Filtering Configuration

Last Updated: 2014-06-02

Selecting Configuration > Filtering Configuration from the main menu area of the Server UI enables you to configure the following functions:

  • Control-plane_UAC_Filtering

  • Control-plane_UAS_Filtering

  • User-plane Filtering

Control-plane UAC Filtering and Control-plane UAS Filtering

Control-plane UAC Filtering - Provides filtering capability for:

    • Peer-to-peer control-plane (SIP) Request messages proxied by the Server. In this case the filtering is applied before the Server processes the Request.
    • Client-to-Server Requests (that is, Server-terminated requests), where filtering is applied before the Server processes the Request
    • Peer-to-peer control-plane (SIP) responses proxied by the Server, where filter is applied after the Server processes the Response
    • Server-to-Client responses (i.e. Server-Initiated responses), where filtering is applied after the Server has processed the associated Client request.

Control-plane UAS Filtering - Provides filtering capability for:

    • Peer-to-peer control-plane (SIP) Request messages proxied by the Server. In this case the filtering is applied after the Server processes the Request.
    • Server-to-Client Requests (thet is, Server-initiated requests), where filtering is applied after the Server processes the Request
    • Peer-to-peer control-plane (SIP) responses proxied via the Server, where filter is applied before the Server processes the Response
    • Client-to-Server responses (i.e. Server-terminated responses), where filtering is applied before the Server has processed the associated Client request.

User-plane Filtering

User-plane Filtering - Provides filtering capability for:

    • Statistics-tracking of RTP/RTCP packets-counts and byte-counts sent to/from endpoints on a particular session.

    • Enabling/Disabling a (fixed) unidirectional delay to the RTP and/or RTCP path of session(s) between particular users.

    • Enabling/Disabling uni-directional packet-discarding to the RTP and/or RTCP path of session(s) between particular users.

See Also

How to Create Custom Error Responses

Control-Plane Filtering Overview

User-Plane Filtering Overview

SIP_User-Plane_API_Filtering-Rule_Specification


Message Accounts

Last Updated: 2014-06-02

Selecting Configuration > Message Accounts from the main menu area of the Server UI enables you to create, remove, and modify of simulated user message-box/mailboxes, which you can use for testing the Message Waiting Indication (MWI) service.

See Also

How to Create Message Accounts


Subscriber Data

Last Updated: 2014-06-02

Selecting Configuration > Subscriber Data from the main menu area of the Server UI enables you to modify (add, remove, edit, or copy) users in the currently-active Subscriber “database”. In addition, you can load subscriber data or save changes you have made to subscriber data.


Subscriber Property Editor

Last Updated: 2014-06-02

From the main menu area of the Server UI, select Configuration > Subscriber Data, then in the Subcriber Data Config window, select a user and click Edit and the Subscriber Property Editor window opens enabling you to modify the following:

  • Identity

  • Misc

  • Security

  • Supplementary Services

Identity

Asserted User ID - Enables you to change — or create for a new user — a value that acts as the Asserted-User-Identity of the subscriber. The value must be in the form of a SIP URI, for example, user@somedomain.com.

Associated User IDs - Enables you to change — or create for a new user — a value or list of values, that acts as Associated Public-User-IDs of the subscriber. The value must be in the form of a SIP URI, for example, "sip:defaultuser@default.com". The list of Associated URIs, specified for the subscriber, is of variable-length.

You must ensure that a particular Public User ID value is not used for more than one (1) subscriber.

MSISDN - Enables you to change the MSISDN associated with the subscriber.

The MSISDN number is utilized when performing interworking between legacy cellular services and IMS-based ones; for example when interworking legacy 3GPP SMS messaging over IMS (where the 3GPP SMS is encapsulated in SIP MESSAGE requests).

The MSISDN must be defined as a valid digit string, for example “1234567890”.

You must ensure that each subscriber is assigned a unique MSISDN number to avoid service conflicts.

Misc

3GPP Special SMS MWI Indication Enabled - This parameter allows configuration of whether, for the associated subscriber, message-waiting information is sent to the user by means of the “3GPP Special SMS Message Indication” mechanism outlined in 3GPP TS 23.040.

When this is enabled, such notifications shall be generated when:

  • The user initially registers to the IMS Server (as a “current state” notification), or

  • When the state of a Message Account associated to the subscriber changes, while the subscriber is registered to the IMS Server.

Security

Authentication

Provides access to various parameters which influence the behavior of the Authentication logic in the server, for example secret-key values, algorithm types, and so forth.

Note: Enter hex values when populating the Secret key, Op variant type, Op variant value, and Rand value fields below.

Common

Auth-Realm - This field is used to specify the Authentication realm/domain value to be used when performing authentication procedures with the subscriber.

Auth-Algorithm - When the underlying authentication algorithm is Milenage, select from the drop-down list box MD5, AKAv1, or AKAv2. This is generally used when testing real world devices.

AKA

Algorithm - DummyXOR - used to facilitate testing of 3GPP test UICCs.

Milenage - used to facilitate testing of UEs using commercial UICCs

Private key - This field is used to specify the ISIM AKA K/Authentication key value used for AKA key generation.

Op value - This field enables you to specify the operator-specific value (either OP or OPc) associated with the ISIM used within the device under test.

RAND value - Enables you to specify the randomized RAND value used as an input parameter to the AKA (v1 and v2)algorithms.

AMF - Enables you to specify the Authentication Management Field (AMF) associated with AKA authentication.

Op type - This enables you to control whether the "OP value" field should be considered as an OP or OPc value when used as an input parameter to the IMS AKA algorithm.

OP = Enter Operator Variable Parameter Value in 16 Byte Hex string format.

OPc = Enter Operator Variable Parameter Value in 16 Byte Hex string format.

RES Length - Enables you to specify the number of octets to use from the calculated AKA RES value when performing AKA authentication procedures.

MD5

You may enter the Username and Password for use when the Auth-Algorithm is set to MD5.

IPsec

Integrity Algorithm: Enables you to select the integrity-protection state and algorithm type.

The supported types are HMAC_MD5_96 and HMAC_SHA1_96.

Encryption Algorithm: Enables you to select the encryption/confidentiality-protection state and algorithm type.

The supported types are AES-CBC (128-bit), DES-EDE3-CBC, and Null.

When the application is running on an OS-version for which IPSec support is not provided, IPSec functionality shall be disabled and a warning message shall be logged upon application startup.

Supplementary Services

Originating Identity Presentation (OIP)

Active: Enables you to select the type of supplementary service which provides caller- identity presentation and blocking capability associated with the originating identity (from the perspective of the terminating user).

The supported types are True, False, and Default.

Originating Identity Restriction (OIR)

Active: Enables you to select the type of supplementary service which provides caller- identity presentation and blocking capability associated with the originating identity (from the perspective of the terminating user).

The supported types are True, False, and Default.

Mode: Enables you to select how the Active caller-identity presentation and blocking capability are applied.

The supported types are Temporary and Permanent.

Temporary Mode: When you have selected Temporary as the Mode, this enables you to select how it is applied.

The supported types are Presentation Not Restricted, Presentation Restricted, and Default.

Restriction Type: Specifies the type/level of identity-restriction to apply when the OIR service is triggered.

The supported types are Asserted Identity and All Private Headers.

The “Default” values denote that the configuration shall behave as per the default-specified values outlined in the XCAP schema for the supplementary-service definition.

Terminating Identity Presentation (TIP)

Active: Enables you to select the type of supplementary service which provides caller- identity presentation and blocking capability associated with the terminating identity (from the perspective of the originating user).

The supported types are True, False, and Default.

Terminating Identity Restriction (TIR)

Active: Enables you to select the type of supplementary service which provides caller- identity presentation and blocking capability associated with the terminating identity (from the perspective of the originating user).

The supported types are True, False, and Default.

Mode: Enables you to select how the Active caller-identity presentation and blocking capability are applied.

The supported types are Temporary and Permanent.

Temporary Mode: When you have selected Temporary as the Mode, this enables you to select how it is applied.

The supported types are Presentation Not Restricted, Presentation Restricted, and Default.

The “Default” values denote that the configuration shall behave as per the default-specified values outlined in the XCAP schema for the supplementary-service definition.

Network-Detection User Busy (NDUB)

Maximum Concurrent Sessions: Enables you to set the number of session establishment attempts (INVITEs) associated with NDUB detection evaluation when the server processes incoming requests.

The value range is 0 to 10 with a default value of 5.

Communication Waiting (CW)

A supplementary service which provides an indication to the UE that no resources are available for an incoming communication. The recipient of the indications can then provide the user with the choice of how to handle the incoming communication (accept, reject, ignore, etc.).

Active: Enables you to select whether CW procedures shall be applied to the associated subscriber (i.e. whether NDUB criteria shall be actively used/considered by the server to trigger CW operation).

The supported types are True and False.

Tascw Duration: Enables you to specify the timer-period associated with CW procedures timer.

The value range is 30 to 120 sec with a default value of 30 sec.


Message

Last Updated: 2014-06-02

The message tab enables you to configure, create, and send an SMS message to the client. You can also set the server response to the UE.

  1. Select Message Type

  2. Message Text

  3. Send Control

1. Select Message Type

You can specify the following SIP MESSAGE Content-Types:

  • Text/Plain: This message Type is an alpha-numeric message with no formatting that you create as shown in section 2 of the figure above.

  • application/vnd.3gpp.sms: When selecting this message type, the functional behaviour shall depend on whether Send_as_hex is also enabled. If “Send as hex” is disabled, the message-text should be an ASCII-string message that shall be dynamically encoded into a (legacy) 3GPP SMS with the required 3GPP SMS headers. If “Send as hex” is enabled, the message-text should be populated with the hex-string representing the pre-encoded 3GPP SMS content to send – whereby this will bypass the internal 3GPP SME entity/state-machine and send the message in a raw/transparent manner, bypassing 3GPP SMS protocol.

  • application/vnd.3gpp2.sms: When selecting this message type, select the Send as hex option and paste the hex string representing the binary encoded message content into the message area (section 2 of the figure above).

The message Type field only influences the MIME content type which is indicated in the "Content-Type" header of SIP MESSAGE signaling primitives.

Checking the [image] option enables the [image] icon. Select this icon to open a browser window where you choose the binary formatted file you wish to send. Note that selecting this option disregards the message you created as shown in section 2 of the figure above.

When using the From binary file capability, the message body section of the transmitted SIP MESSAGE is populated with the raw content contained in the specified file, regardless of the Message Type setting selected as shown in section 1.

For a client connected to the server via UDP transport type it is your responsibility to ensure that the content length of the specified file does not cause the resultant UDP datagram to exceed the allowed maximum length. In such a circumstance, the target client does not successfully receive the datagram. It is recommended that you configure clients to use TCP transport type when utilizing the “From binary file “ capability.

2. Message Text

  • If you have selected Text/Plain in the "Select Message Type" area above, then type the message you wish to send here.

  • If you selected application/vnd.3gpp.sms and “Send As Hex” is unchecked, then type the text message you wish to send here.

  • If you selected application/vnd.3gpp.sms or application/vnd.3gpp2.sms and “Send As Hex” is checked/enabled, then paste the encoded hex-string into this area.

    • Note that it is not currently valid to send an application/vnd.3gpp2.sms message without also enabling “Send As Hex”.

3. Send Control

  • Send as hex: Enables you to send the message specified in hexadecimal format. When this option is selected, the Message Text must be an even number of characters from the following set [0-9, a-f, A-F]. If these conditions are not satisfied, an error is generated when an attempt is made to send the message.

  • Send Message: Activates the sending of the custom message content. The content is provided either by the Message Text input, or from a specified file (as outlined in sections 1-3 above).

  • Send Default 3gpp.sms: Sends a generic, pre-defined, and pre-encoded 3gpp binary message.

  • Send Default 3gpp2.sms: Sends a generic, pre-defined, and pre-encoded 3gpp2 binary message.

Default 3gpp2 message sends a fixed hex sequence without updating the message sequence number. UEs receive the message when first sent and then do not display subsequent message re-sending until their SMS receive buffer has been cleared by a power off-on cycle.

4. Alternate Message Response

Numerous response options are available:

  • [Normal]: Alternate-Response override is disabled and the associated SIP request method-type is processed using normal rules and behavior.

  • OK: Sends the response "OK" back to client after receiving message from client.

  • None: Inhibits the server response (as in simulation of a lost message) .

  • Accepted: Sends the response "Accepted" back to client after receiving message from client.

  • Bad Request: Sends the response "Bad Request" back to client after receiving message from client.

  • Not Found: Sends the response "Not Found" back to client after receiving message from client.

  • Server Error: Sends the response "Server Error" back to client after receiving message from client.

  • Bad Gateway: Sends the response "Bad Gateway" back to client after receiving message from client.

  • Service Unavailable: Sends the response "Service Unavailable" back to client after receiving message from client.

See Also

Control


Control

Last Updated: 2014-06-02

This tab enables you to control the Server, Registration, Authentication, and the SIP Response.

  • Server Control

  • Registration Control

  • Authentication Control

  • Response Control

Server Control

  • Start: Starting the server opens the network sockets for message reception.

  • Stop: Stopping the server results in all current transaction/dialog and session contexts to be cleared and for the listening network sockets to be closed.

Registration Control

  • Enables you to selectively de-register or force re-registration of a specific client which is currently registered on the Server.

  • The action is performed on the currently selected client.

  • The de-register or re-registration procedures are performed as per RFC3680 and involve the transmission reg-event NOTIFY messages where the selected client is subscribed to this event.

Authentication Control

  • Enables high-level control of whether Authentication is enabled.

  • Enables AKA authentication SQN sequence numbers to be explicitly reset for the selected client.

Response Control

  • Enables high-level override of the response associated with REGISTER or MESSAGE SIP Requests which are received (for example, to force error conditions).

  • Enables you to configure a forced-failure to Authentication attempts by IMS Clients.

See Also

Message

Overview-Server UI


How to Create Custom Error Responses

Creating Custom Error Responses

Last Updated: 2014-06-02

The topic provides directions on creating custom error responses with the Custom SIP Error Responses user interface in the IMS-SIP Server application.

Custom Error Responses Overview

You may use the “Custom Error Response” specification utility in conjunction with Control-Plane filtering, on the FilterUAC filtering point, to facilitate the transmission of flexible/customized SIP Response content, in response to particular received SIP Request messages.

Utilizing custom-errors involves two setup components:

  1. Specification of custom error response content,

  2. Custom-error response triggering filtering rules.

Specification of custom error response content

Custom error-response content can be configured using either API and GUI, only the GUI case is covered here.

The GUI control for specifying custom error-response content is available using the following menu item: “Configuration->Custom SIP Error Responses”.

This provides a GUI dialog similar to the following:

Adding a new (empty) custom error response:

To add a new (empty) custom error-response entry, simply click “Add”.

This adds a new custom error-response entry with an associated unique auto generated “ID” value, similar to the example shown below:

Editing the new custom-response entry:

The custom error-response entry can be edited either by double-clicking on the entry, or by selecting it and clicking on “Edit”.

This produces an editing dialog similar to the following:

Note that this is a very simple editing dialog, and the you are expected to input the SIP Response text in here.

An easy starting point for content is to perform “Call Flow Logging” in the IMS Server application to capture a successful IMS registration then the “200 OK” response text can simply be copy/pasted into here as a starting point:

Notice that there is some basic validation in this editor dialog that attempts to prevent the user from committing erroneous content as a custom error-response.

Some general guidelines on the validation criteria are as follows:

    1. Must be a properly formatted SIP Response.

    2. For SIP Response content which does not contain a body, the text MUST end in a double “CRLF” after the last header-line (which also contains a CRLF).

    3. The Status code cannot be in either the 1XX or 2XX range (i.e. must contain a status-code from a classification group which is considered both final, and an error).

    1. 1XX codes are unsuitable since they are provisional (i.e. not final codes),

    2. 2XX codes are unsuitable since they are success codes (i.e. not error codes)

In compliance with the above guidelines, the example content is modified such that:

  • There is a trailing double CRLF following the last header-line,

  • The status status-code is changed to “666”,

  • The description is changed to “CUSTOM DESCRIPTION” (optional).

Some of the other fields are also tidied up slightly (or removed), and the content now looks something like:

Notice that the content is now considered valid, and you can commit the changes at this stage if desired.

There is, however, a remaining issue regarding the message content.

The content is not very generalized, and contains many transaction-specific and dialog-specific identifiers which are not applicable more generally. For example the dialog-identifier (From-tag, To-tag, Call-ID) values are liable to vary when processing Requests received from different IMS clients, at different times etcetera and the branch/transaction-ID within the Via header will vary between transactions.

It is important that these values in the response correlate accordingly with the values received in the associated SIP Request to which this Response is being returned.

To facilitate this, the IMS Server application provides special Substitution Tokens/Macros, whereby the token is replaced (dynamically) when the custom-response is selected/transmitted, based on values from the associated Request that was received (to which this response is being sent).

Substitution-Tokens:

All of the supported substitution-tokens support a common delimitation format, to differentiate them from normal/fixed string content.

Delimiting format

substitution-token = “{{” token-identifier “}}”

For the purposes of describing the semantics of the substitution-tokens, the following SIP Request shall be used as the example message which causes the custom-response to be generated and sent from the IMS Server application:

sample_request =

INVITE sip:+10000000002@test.3gpp.com SIP/2.0

Via: SIP/2.0/UDP 192.168.2.51:5060;branch=z9hG4bK42328944

Via: SIP/2.0/UDP 192.168.2.51:5080;branch=z9hG4bK-524287-1---df4792097600ff56;rport

Max-Forwards: 70

From: "MyDisplayName1"<sip:e911node@test.3gpp.com>;tag=ca231b25

To: <sip:+10000000002@test.3gpp.com>

Call-ID: COYRcaubeYah5dPnlLSBNQ..

CSeq: 1 INVITE

Contact: <sip:e911node@192.168.2.51:5080>;+sip.instance="<urn:uuid:7BEC2D81-8E3C-5744-DB80-E6B8380D7577>"

Content-Type: application/sdp

Content-Length: 222

Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY, MESSAGE, REGISTER, SUBSCRIBE

Min-SE: 90

Session-Expires: 3000

Supported: replaces, timer

User-Agent: Agilent_IMS-SIP_Client/6.4.0.0

v=0

o=- 37516512 37516512 IN IP4 192.168.2.51

s=http://www.portsip.com

c=IN IP4 192.168.2.51

t=0 0

m=audio 10000 RTP/AVP 123 101

a=rtpmap:123 AMR/8000

a=rtpmap:101 telephone-event/8000

a=fmtp:101 0-16

a=sendrecv

The available substitution tokens are provided in the table below, along with the example value that is substituted in the Custom Response message (based on the above example request):

Substitution Token | Example Dynamically substituted value (for a Response to sample_request)
{{RXREQ.CALLID}} | COYRcaubeYah5dPnlLSBNQ..
{{RXREQ.CSEQ}} | 1 INVITE
{{RXREQ.CSEQ.METHOD}} | INVITE
{{RXREQ.CSEQ.SEQNUM}} | 1
{{RXREQ.FROM}} | "MyDisplayName1"<sip:e911node@test.3gpp.com>;tag=ca231b25
{{RXREQ.FROM.NAME}} | MyDisplayName1
{{RXREQ.FROM.TAG}} | ca231b25
{{RXREQ.FROM.URI}} | sip:e911node@test.3gpp.com
{{RXREQ.TO}} | <sip:+10000000002@test.3gpp.com>
{{RXREQ.TO.NAME}} | (null)
{{RXREQ.TO.TAG}} | (null)
{{RXREQ.TO.URI}} | sip:+10000000002@test.3gpp.com
{{RXREQ.VIAHEADERS}} | Via: SIP/2.0/UDP 192.168.2.51:5060;branch=z9hG4bK42328944 Via: SIP/2.0/UDP 192.168.2.51:5080;branch=z9hG4bK-524287-1---df4792097600ff56;rport
{{RXREQ.VIAHEADERS.TOP}} | SIP/2.0/UDP 192.168.2.51:5060;branch=z9hG4bK42328944
{{RXREQ.VIAHEADERS.TOP.BRANCH}} | z9hG4bK42328944

Therefore we can make our example custom-response content more robust by replacing some of the fixed/raw identifier values with the appropriate substitution-tokens above.

Our original content of:

Can be modified to:

This final version provides a much more flexible response content.

Finally, we can commit the change by clicking on “OK”.

This will result in the Custom SIP Error Responses dialog looking something like:

Note the “CSeq.Method” column shows “[undefined]” since we have specified a substitution token and therefore the value is not statically known (and is only determined when generating a custom response dynamically due to a received SIP Request).

Finally, as a useful tip, it is possible to copy (to clipboard) the “ID” value associated with a particular custom response, by right-clicking on the custom-response row, which will bring up a context-sensitive menu containing a “Copy ID” option.

This is very useful when performing the next part of the procedure (configuring filtering rules), where the custom-response ID value must be specified as a filter-rule action parameter.

Custom-error response triggering/filtering rules

The previous section dealt with how to specify custom error-response content (that is, what the custom response content is), whereby it is essentially possible to compile a dictionary of various custom error-responses, where the dictionary key is the “ID” value of the custom-response entry.

However, it is still required to configure the Server to specify when the custom response content shall be used.

This is achieved by utilizing Control-Plane filtering (at the FilterUAC filtering point) by adding filtering-rules with a specified action-type of “Custom Response”, and an action-param value which specifies the “ID” value of the custom-response message-content to select and send, in response to the received request which triggered the associated filter-rule.

For more information and examples on configuring the control-plane filtering, refer to Control-Plane Filtering Overview.

See Also

Control-Plane Filtering Overview


Control-Plane Filtering Overview

Last Updated: 2014-06-02

The topic provides directions on using Control-Plane Filtering in conjunction with Custom Error Responses to creating custom error responses with the Filtering Configuration user interface in the IMS-SIP Server application.

Control-Plane Filtering Architecture Overview

The control-plane filtering functionality provides the ability to perform customized actions which are triggered according to specific parameters within received or transmitted control-plane messaging.

The general architecture of the filtering mechanism is outlined in the following figure:

The filtering capabilities are provided at two points in the IMS Server application – identified as FilterUAC and FilterUAS in the figure, respectively.

FilterUAC provides the filtering capability for:

  • Peer-to-peer control-plane (SIP) Request messages proxied via the Server (where filtering is applied before the Server processes the request).

  • Client-to-Server Requests (that is, Server-terminated requests), where filtering is applied before the Server processes the request.

  • Peer-to-peer control-plane (SIP) responses proxied via the Server, where filtering is applied after the Server processes the response.

  • Server-to-Client responses (that is, Server-initiated responses), where filtering is applied after the Server has processed the associated Client request.

FilterUAS provides the filtering capability for:

  • Peer-to-peer control-plane (SIP) Requests messages proxied via the Server (where the filtering s applied after the Server processes the request)

  • Server-to-Client Requests (that is, Server-Initiated requests)

  • Peer-to-peer control-plane (SIP) Responses proxied via the Server, where filtering is applied before the Server processes the response.

  • Client-to-Server Responses (that is, Server-terminated responses), where filtering is applied before the Server has processed the associated Client response.

The configuration of the filtering points is available by both the GUI and the API.

The GUI provides the following items:

Within the GUI, “Control-Plane UAC Filtering” and “Control-Plane UAS Filtering” provide access to the configuration of the FilterUAC and FilterUAS filtering-points respectively.

Each filtering point is controlled by means of a filter-rule table, which specifies a sequence of filter-rules to apply against received/transmitted SIP (control-plane) messages.

Filter-Rule Overview

A filter-rule comprises two main components:

    1. Conditional/Match evaluation criteria

    2. A filter-action

The evaluation-criteria specifies the conditions under which a filter-rule returns a “positive” match for a given message against which it is evaluated.

The filter-action specifies the type of action (and associated action-parameters) to apply when the evaluation criteria are satisfied for the filter-rule.

A given filtering-point may contain multiple filter-rules whose evaluation-criteria match against a particular received/transmitted message that is being evaluated. In such a case, only the first matching filter-rule shall be applied for the given message being evaluated.

Detailed information regarding the available parameters associated with the evaluation-criteria and action components can be found in Control-Plane_Filter-rule_specification.

Examples of GUI-configured Filter rules

The following screen-capture shows example filter-rules that have been specified for the FilterUAC filtering point.

The examples above specify the following rules:

Index | Rule-ID | Description
1 | 1606090480 | Delays all incoming REGISTER requests from “sip:clientA@test.3gpp.com” by 200ms.
2 | 2010713445 | Discards all non-initial INVITEs from “sip:bill@agilent.com” to “sip:dave@agilent.com”
3 | 1412610407 | Returns a custom-defined error response message (identified by ID = “m889467504”) for any MESSAGE requests targeting “sip:sc@agilent.com”
4 | 1639937965 | Triggers an API-registered callback for all peer-to-peer requests originating from “sip:clientB@test.3gpp.com”.

Control-Plane Filter-Rule Specification

A description of the (GUI-accessible) specification fields associated with a filter-rule is as follows:

Field Descriptions

Field

Description

Category

Rule ID

An auto generated unique ID for identifying the filter-rule.

Rule Identification

From URI

A value against which the URI value of the “From” header is compared for a match.

Filter-Rule Evaluation Criteria

Request URI

A value against which the “Request-URI” of the SIP Request is compared for a match.

For SIP Responses, this field value is compared against the URI of the “To” header.

Message Type

Specifies whether this rule applies only to SIP Requests or Responses.

Message Name

Specifies the value of the CSeq “Method” against which this filter applies,

Can be a comma-seperated list of values.

In-Dialog Only

Specifies whether this filter-rule only applies to messages which are evaluated as being “in-dialog” (by virtue of whether the evaluated message contains a “To-tag” value).

Filtering Path

Denotes the filtering-path to which this rule applies.

“Server Associated” matches only requests/responses which terminate at the Server (for example: REGISTER).

“Peer-to-Peer” matches messages which target some other endpoint/user-agent (ex: INVITE between IMS clients).

Trigger Indication

Specifies whether a registered API callback shall be invoked (if one is registered) when the filter rule is triggered.

API callback triggering

Action Type

Specifies the action-type to invoke when the API filter-rule is triggered following successful/matching evaluation.

Filter-Action specification

Action Params

Specifies (action-specific) parameter values. For more information, see Action_Parameters table below.

Description of Action Parameters

Action Type

Action Parameters

Example

Description

none

-

-

No parameters.

Performs no action, other than to increment a trigger-counter associated with the filter-rule and processing the message normally.

delay

delay duration

(ms)

200

(delay for approx 200ms)

Parameter is an integer value between 0 and 15000 specifying the duration (in ms) to delay the message.

The message is artificially delayed by this duration before further processing on the message is performed.

discard

-

-

No parameters.

Discards the message without further processing.

Custom

response

Custom response

Msg-ID

m889467504

Parameter is the ID value of a defined “custom error response” message to send as a “response override”.

When this action is triggered, the specified custom response is returned and no further processing is applied to the received/triggering message.

Note:

  • This action is only valid for FilterUAC filtering point.

  • If a rule specifying this action is triggered, and a custom error response matching the specified ID does not exist, the action taken shall be the same as the “discard” case.

See Also

Custom SIP Error Responses

How to Create Custom Error Responses


How to Create Message Accounts

Using Message Accounts

Last Updated: 2014-06-02

The topic provides directions on creating and modifying simulated message accounts with the Message-Account Data Config user interface in the IMS-SIP Server application.

Message Accounts Overview

The IMS Server application provides the ability to create and modify simulated message accounts (or mailboxes) associated with subscribers, for the purposes of testing Message Waiting Indication (MWI) functionality.

The GUI interface into the Message Account Manager is shown below:

This interface provides the ability to add/remove simulated message accounts, modify the URI associated with account and to deposit simulated messages into a specific account.

Adding a new message account

An example mailbox/account for “sip:bill@agilent.com”, can be added as follows:

  • First click the “Add” button to add a new mailbox with default state (and a unique account-id).

  • Modify the “Account-User URI” by double-clicking on the associated table-cell and typing the required SIP URI value.

The “Account-User URI” field is essentially the SIP-URI identifier associated with the mailbox resource, and should match the URI to which the associated SIP user-agent will SUBSCRIBE for “message-summary” event notifications. This will typically be the same as the SIP-URI of the subscriber.

For example: subscriber/user “sip:bill@agilent.com” would typically SUBSCRIBE to the “message-summary” event for the target “sip:bill@agilent.com”.

Depositing messages

Once a message account has been created, it is possible to deposit simulated messages into a mailbox.

To deposit a message, simply populate the various message-fields as required, select the appropriate message account and click “deposit”.

The example below shows a simulated Fax message that has been deposited into the message-account associated with “sip:bill@agilent.com”.

Notes:

  1. Depositing a simulated message does not actually create a message (containing a body), but simply generates the message-header content and stores it into the target mailbox.

    For further clarification – it is the message-header content which is used in mailbox notifications (such as NOTIFY of the “message-summary” event). Since the message-body of messages is only significant when a user actually retrieves the message (for which no mechanism is currently provided) there is no need (and therefore no provisions in the application) to provide a message-body.

  2. When the state of a specific mailbox changes (ex: when content is deposited, the mailbox is cleared, or added/removed), this triggers a notification event.

    When the notification event is triggered, this causes a notification to be sent in 2 possible ways:

    1. If an IMS-user has previously subscribed (via SIP “SUBSCRIBE” request) to the “message-summary” event for the resource identified by the “Account-User URI” value associated with the modified mailbox, then an IMS NOTIFY message shall be sent to the subscriber (as per 3GPP MWI functionality),

    2. If the “Account-User URI” associated with the mailbox has an associated IMS subscriber profile (where the subscriber-profile has an Asserted-Identity matching the “Account URI” of the mailbox), and the subscriber-profile has both a valid MSISDN value and has the “3GPP Special SMS MWI Indication Enabled” parameter set to “true”, then a “Special SMS Message Indication” 3GPP SMS (as per 3GPP TS 23.040) shall be sent to the associated MSISDN, containing content associated with the mailbox state.

  3. The “Special SMS Message Indications” are also sent by the IMS Server to an IMS user during initial registration, if the subscriber-profile associated with the registering user is configured as above.

  3. The text-fields associated with various message-header values (ex: “To”, “From”, “Subject”) are interpreted as raw-string values and are populated in notification content (e.g. NOTIFY messages) as such.


Server API Reference

Last Updated: 2014-06-02

This topic provides details of the API connectivity for the E6966B IMS-SIP Network Emulator. This API provides you with the ability to automate control of all aspects of the Server Application.

The Server must be running in order to use this API.

The Server API control is provided by the following .NET-based DLL: Agilent.ImsSip.ServerComm.dll.

This DLL is provided as part of the E6966B IMS-SIP Server Emulator installation and can be located as follows:

  • For Windows XP:
    C:\Program Files\Agilent\E6966B\API Tools\Agilent.ImsSip.ServerComm.dll

  • For Windows 7 (64-bit):
    C:\Program Files (x86)\Agilent\E6966B\API Tools\Agilent.ImsSip.ServerComm.dll

See Also

Alphabetical List of API Methods (Server)

Alphabetical List of Structures (Server)

Interfaces by Category (Server)

Reference of Enumerated Types (Server)

Programming Examples and Other Reference Material

COM Wrapper

Example Code Using COM Interface (Server)

COM Type/Class Identifiers (Server)

Using the COM Interface (Server)


Alphabetical List of API Methods (Server)

Last Updated: 2014-06-02

  • AddFilterRule

  • AddNewSubscription

  • ApplySubscriptionChanges

  • ClearAll

  • ClearCallFlow

  • ClearError

  • ClearStatus

  • Close

  • DeRegisterClient

  • DuplicateExistingSubscription

  • GetActiveListeners

  • GetActiveNic

  • GetFilterRuleById

  • GetFilterRuleByIndex

  • GetRecentConfigurations

  • GetSessionDataSnapshot

  • GetSessionDataSnapshotByFromUri

  • GetSipUriForServiceType

  • GetSubscriptionData

  • GetTriggerCounterById

  • GetTriggerCounterByIndex

  • GetValidListeners

  • GetValidNics

  • Initialize

  • IsRegistered

  • LoadConfigurationData

  • LoadSubscriberData

  • ModifyFilterRuleById

  • ReadError

  • ReadStatus

  • RegistrationClear

  • RegistrationIsFeatureTagSupported

  • RemoveAllFilterRules

  • RemoveClient

  • RemoveFilterRuleById

  • RemoveSubscription

  • RequestClear

  • ReRegisterClient

  • ResetAllSessionDataStatistics

  • ResetAllTriggerCounters

  • ResetTriggerCountersById

  • ResetTriggerCountersByIndex

  • ResetSQN

  • SaveCallFlow

  • SaveConfigurationData

  • SaveError

  • SaveStatus

  • SaveSubscriberData

  • SelectClient

  • Send

  • SendDefault3gpp

  • SendDefault3gpp2

  • SendFromFile

  • SetActiveListeners

  • SetActiveNic

  • SetActivePort

  • SetSipUriForServiceType

  • SetUserPlanePassthroughState

  • Start

  • StartCallFlow

  • StopCallFlow

  • StopListeners

  • TerminateSession

  • TerminateSession_2


Alphabetical List of Structures (Server)

Last Updated: 2014-06-02

  • MediaTransportLegStats

  • MediaTransportLinksStats

  • SecurityConfigStruct

  • SecAuthConfigStruct

  • SecIpsecConfigStruct

  • SuppServConfig_NdubStruct

  • SuppServConfig_OipStruct

  • SuppServConfig_OirStruct

  • SuppServConfig_TipStruct

  • SuppServConfig_TirStruct

See Also

Alphabetical List of API Methods (Server)

Interfaces by Category (Server)

Reference of Enumerated Types (Server)


Example API Usage (Server)

Last Updated: 2014-06-02

This section outlines how to use the provided Agilent.ImsSipServerComm.dll to control a running instance of the E6966B IMS-SIP Server Emulator application.

The provided API is intended for use by .NET-based applications, and provides a convenient wrapper to utilize a WCF interface for controlling the IMS-SIP Server application.

To access any of the API methods, a reference to the Agilent.ImsSipServerComm.dll needs to be added to the .NET project/application calling the API.

The following example shows the basic calls for initializing the WCF interface connection and performing some basic logging control activities.

Example [C#]

// the following using statements should be included at the start of the source-code file

using Agilent.ImsSip.ServerComm; // Access to API methods/interfaces

using Agilent.ImsSip.ServerComm.ServiceReferenceSip; // Access to various type definitions

public class MyClass

{

// defining a reference to the interface

private Agilent.ImsSip.ServerComm.API serverAPI;

// initializing the API to connect via WCF to application running on PC at IP address

// 192.168.1.1:8240

public bool Init(void)

{

serverAPI = new Agilent.ImsSip.ServerComm.API();

return serverAPI.Connection().Initialize(“192.168.1.1”, 8240);

}

// closing the API connection

public void UnInit(void)

{

serverAPI.Connection().Close();

serverAPI = null;

}

// capture a log of the call-flow for “duration” milliseconds and save to file

public void CaptureCallFlowLog(int duration, string filename)

{

if (serverAPI != null)

{

serverAPI.Logging().ClearCallFlow();

serverAPI.Logging().StartCallFlow();

System.Threading.Thread.Sleep(duration);

serverAPI.Logging().StopCallFlow();

serverAPI.Logging().SaveCallFlow(filename);

}

}

}


Interfaces by Category (Server)

Last Updated: 2014-06-02

This section provides a reference guide for the API provided by the E6966B IMS-SIP Server Emulator Software. The API is logically split into a number of categories, dealing with different areas of functionality. They are listed below:

  • Server_Connection

  • Server_Activation_and_Control

  • Authentication

  • Call_Control

  • Client_Registration

  • SMS_Send

  • Alternate_Responses

  • ISignalingControl

  • ISubscriptionManager

  • Signaling_Protocol

  • Server_Logging

Server Connection

The IConnection interface to the API provides the connection to the SIP Server application on the local or remote host using the Windows Communication Foundation (WCF) service. This provides a remote control connection to the SIP Server Application interface.

Server Activation and Control

The IServer interface to the API allows License activation and Server control. License validation is required before operational use of the Agilent SIP Server. Server Control method provide ability to start/stop the Server and query the Server version.

Authentication

The IAuthentication interface to the API enables SIP authentication to be configured on the SIP Server. Authentication is invoked during SIP Client registrations. Authentication may be enabled or disabled. Depending on the authentication type selected, different authentication parameters apply. The types of authentication supported are: AKAv1, AKAv2, and MD5.

Call Control

The ICallControl interface to the API enables call-control modification and querying.

Client Registration

The IClientControl interface to the API enables SIP Server access and control over the current list of registered SIP Clients. The SIP Server may query the list of currently registered clients, select remove, de-register, and re-register any client using the following methods:

SMS Send

The IMessage interface on the SIP Server provides the ability to send any registered Clients SMS messages of types 3gpp, 3gpp2, or plain text. The SMS interface is:

Alternate Responses

The IAlternateResponse interface on the SIP Server provides the ability to configure automatic alternate responses to all incoming messages for testing SIP Client/DUT error response handling purposes.

Signaling Control

The ISignalingControl interface is used to modify various SIP-Signaling related controls.

Subscription Manager

The ISubscriptionManager interface is used to is used to configure or modify the active user(s) subscription-data.

Signaling Protocol

The ISignaling interface on the SIP Server enables access to all incoming SIP Signaling Protocol message and response header field values. The SIP Signaling Protocol message/responses are broken into two categories: Registration and Request (Non-Registration). Registration protocol message/responses are all message/responses relating to the SIP Registration process. Request (Non-Registration) SIP Signaling Protocol messages are all message/responses that are not registration related (for example: SMS and VoIP).

Server Logging

The ILogging interface on the SIP Server enables access to the various logging modules that track all IMS-SIP operations. It is ideal for debugging, test verification and validation, and monitoring the state of SIP Server.


Interface: IAlternateResponse

Last Updated: 2014-06-02

This interface performs the following functionality:

  • Ability to change/override the SIP responses generated by the Agilent SIP Server for certain incoming/received SIP requests

  • This facilitates testing the behaviour of a SIP Client when receiving certain error conditions.

Two main mechanisms are available to provide this capability:

  • Message-Response_overrides

  • Custom_Error-Responses

Message-Response overrides

Message-Response-Overrides are only currently available for the following received SIP Request methods:

Request Method Type | Associated IAlternateResponse property
REGISTER | RegisterResponse
MESSAGE | MessageResponse

For example, The “RegisterResponse” property can be configured to a value of “NotFound” which will cause the server to apply an unconditional override when processing incoming “REGISTER” requests to always respond with a “404 Not Found” response.

Message-Response-Overrides are applied and administered globally/unconditionally.

Custom Error-Responses

Custom Error-Responses are used in conjunction with control-plane filtering to provide a finer (and more flexible) control of custom/overridden responses than the Message-Response-Overrides, but are also more somewhat more complex.

Utilizing these custom-errors involves 2 setup components:

    1. Interface: IAlternateResponse#Definition_specification_of_the_custom-error_response_message_content:

    2. Custom-error response triggering.

Definition/specification of the custom-error response message content:

The methods provided by this interface enable setup step (1) above – providing a means to add/remove/modify custom error-response message content.

For more details associated with custom-response content, including details of using dynamic substitution-tokens, refer to How to Create Custom Error Responses and Control-Plane Filtering Overview.

Custom-error response triggering:

Control-plane filtering (outlined in Control-Plane API Filtering-Rule Specification) is used to specify/control the triggering conditions under which a defined custom-error response is selected for overriding responses.

By utilizing the “custom_response” action of a control-plane filter-rule, it is possible to specify that when a particular trigger-condition is satisfied by an incoming request, a particular custom-response (specified by the custom-response “id”) shall be selected and transmitted as a response.

Methods:

AddCustomResponse

ModifyCustomResponseById

RemoveCustomResponseById

RemoveAllCustomResponses

LoadCustomResponseData

SaveCustomResponseData

Properties:

Property | Action | Type | Description
MessageResponse | [set/get] | AltRespMessageType | Enables configuration of a Message-Response-Override associated with incoming MESSAGE requests.
RegisterResponse | [set/get] | AltRespMessageType | Enables configuration of a Message-Response-Override associated with incoming REGISTER requests.

See Also

Custom SIP Error Responses

How to Create Custom Error Responses

Control-Plane Filtering Overview


Interface:IAuthentication

Interface: IAuthentication

Last Updated: 2014-06-02

This interface enables SIP authentication to be configured on the SIP Server. Authentication is invoked during SIP Client registrations. Authentication may be enabled or disabled. Depending on the authentication type selected, different authentication parameters apply. The three types of authentication supported are: MD5, AKAv1, and AKAv2.

Methods:

  • ResetSQN

Properties:

Property | Action | Type | Description
[OBSOLETE] AkaAlgorithmType | [set/get] | AuthAkaAlgorithmType | Set or get the AKA-specific authentication algorithm to be used in the comparison.
[OBSOLETE] AkaResLength | [set/get] | unsigned integer | Configures the length (in bytes) of the RES value to use during AKA authentication. Valid range is 4-16.
[OBSOLETE] AlgorithmType 1 | [set/get] | AuthAlgorithmType | Specifies the SIP Server Authentication algorithm used when performing Authentication procedures. May be set to one of these AuthAlgorithmTypes: AKAv1, AKAv2, or MD5.
[OBSOLETE] AMF | [set/get] | string | Specifies the Authentication Management Field (AMF) value to use as (one of ) the input values to the Authentication algorithm. Note: This string value must only be composed of precisely 4 hex-characters.
ComparisonType | [set/get] | AuthComparisonType | Enables configuration of how the Authentication comparison is performed. For example, it provides the capability to force authentication failure responses.
[OBSOLETE] Enable 2 | [set/get] | bool | Configures whether or not Authentication procedures are enabled (and required by the Server).
[OBSOLETE] OP | [set/get] | string | Specifies the OP/OPc value to use as (one of) the input values to the Authentication algorithm. Note: This string must only be composed of precisely 32 hex-characters.
[OBSOLETE] OpType | [set/get] | AuthOpType | Specifies whether the value in the OP property is treated as an OP or an OPc value-type.
[OBSOLETE] Password | [set/get] | string | Specifies the password string to use during MD5 authentication procedures.
[OBSOLETE] RAND | [set/get] | string | Specifies the RAND value to use as (one of) the input values to the Authentication algorithm. Note: This string must only be composed of precisely 32 hex-characters.
[OBSOLETE] Realm | [set/get] | string | Specifies both the realm input-value for Authentication algorithm calculations, and also the domain/realm associated and controlled by the Server application (which is used during URI resolution. For example: when converting from a TEL URI.)
[OBSOLETE] SecretKey | [set/get] | string | Specifies the K value to use as (one of) the input values to the Authentication algorithm. Note: This string must only be composed of precisely 32 hex-characters.
[OBSOLETE] UserName | [set/get] | string | Specifies the username string to use during MD5 authentication procedures.

  1. The property AlgorithmType configures the SIP server to use AKAv1, AKAv2, or MD5 algorithms in all subsequent authentication checks. AKAv1 and AKAv2 also depend on "AkaResLength" property.

    1. If AlgorithmType is set to AKAv1, the following authentication configuration properties/method apply: ComparisonType, SecretKey, OpType, RAND, AMF, AkaAlgorithmTYpe, and ResetSQN.
    2. If AlgorithmType is set to AKAv2, the following authentication configuration properties/method apply: SecretKey, Op, OpType, RAND, AMF, ComparisonType, AkaAlgorithmType, and ResetSQN. All other parameters are extracted from the SIP messaging received by the client performing Authentication.
    3. If AlgorithmType is set to MD5, the following authentication configuration properties apply: Realm, ComparisonType, Username, and Password.

  2. Property Enable enables or disables Authentication. Parameter configuration must be performed prior to enabling Authentication (See ResetSQN method for more information). Upon receiving a REGISTRATION method from a DUT/UE SIP Client, the SIP Server responds with a 401 AUTHENTICATION CHALLENGE message. The DUT/UE SIP Client then sends another REGISTRATION message containing the authentication response. The authentication response information is verified by the SIP Server service. If the verification is successful, the SIP Server responds with an OK message. If the authentication response fails, the SIP Server service responds with an UNAUTHORIZED message.


Method: ResetSQN

public void ResetSQN();

Resets the SIP Server SQN in AKA Authentication configurations.

Arguments

None

Returns

None

Notes

Resets the Authentication Sequence number. This may be used to test the UE's ability to re-sync the SQN.

See Also

Interface:IAuthentication


ICallControl - Interface

Interface: ICallControl

Last Updated: 2014-06-02

This interface to the API enables call-control modification/querying .

Methods:

  • GetSessionDataSnapshot

  • GetSessionDataSnapshotByFromUri

  • ResetAllSessionDataStatistics

  • TerminateSession (Method)

  • TerminateSession_2 (Method)

Properties

None

See Also

ICallData


GetSessionDataSnapshot (Method)

Method: GetSessionDataSnapshot

List<ICallData> GetSessionDataSnapshot();

Gets the session-data (Call-ID, tags, transfer-stats, and so forth) associated with all sessions tracked by the Server.

Arguments

None

Returns

Possible return values are:

List<ICallData>

A list of session-data structures which contain detailed information about the SIP session.

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


GetSessionDataSnapshotByFromUri (Method)

Method: GetSessionDataSnapshotByFromUri

List<ICallData> GetSessionDataSnapshotByFromUri (string fromUri);

Gets the session-data (Call-ID, tags, transfer-stats, and so forth) for sessions originated from the specified "from-uri".

Arguments

fromUri

[in]

The URI associated with the initial session-originator of all sessions for which data is returned.

Returns

Possible return values are:

Returns | Parameter | Description
List<ICallData> | fromUri | A list of session-data structures which contain detailed information about all sessions originated from the specified "from-uri".

See Also

ICallControl


ResetAllSessionDataStatistics (Method)

Method: ResetAllSessionDataStatistics

void ResetAllSessionDataStatistics();

Performs a reset of the Tx or Rx throughput counters associated with all sessions tracked by the Server.

Arguments

None

Returns

None

See Also

ICallControl


ICallData - Interface

Interface: ICallData

Last Updated: 2014-06-02

This interface to the API provides access to various session-specific statistics or values.

Methods:

None

Properties

Property | Action | Type | Description
CallID | [get] | string | The SIP Call-ID value associated with this session.
OriginatingTag | [get] | string | The dialog-tag associated with the originating client of this session.
OriginatingUri | [get] | string | The URI of the client which performed the initial INVITE during call-setup.
TerminatingTag | [get] | string | The dialog-tag associated with the terminating client of this session.
TerminatingUri | [get] | string | The URI of the client which received the initial INVITE during call-setup.
TransportLinkStats | [get] | List<MediaTransportLinksStats> | Provides access to the various real-time statistics associated with user-plane traffic that has been proxied through the server
SessionState | [get] | CallSessionState | The current state of the associated session (as tracked by the IMS server application)
SessionExpires | [get] | uint32 | The current period after which the associated session is considered expired (as tracked by the IMS server application). If/when the SessionExpires period elapses (without a session-refresh) the server shall implicitly clear/remove all internally cached data/state associated with the session

Notes

  1. CallData is only collected (and valid) when “User-Plane passthrough” is enabled in the IMS Server application. See SetUserPlanePassthroughState for more information.

See Also

ICallControl

IUserPlaneConfig


MediaTransportLinkStats - Structure

Structure: MediaTransportLinksStats

Last Updated: 2014-06-02

This structure available in the API provides access to various statistics associated with each transport-link (media-stream) of this session.

Properties:

None

Fields

Field | Type | Description
MediaType | string | The media type as included in the SDP offer/answer during session-establishment/reconfiguration. (For example, audio media is “audio”, video-media is “video” and so forth.)
OrigTransportLegStats | MediaTransportLegStats | A snapshot of the statistics associated with the originating transport-leg. The originating transport-leg (in the context of media proxied via the server) is the leg/segment associated with traffic between the call-originator and the server.
OrigTransportLegTranferState | MediaTransferStateEnum | The current transfer-state of the originating leg.
TermTransportLegTranferState | MediaTransferStateEnum | The current transfer-state of the terminating leg.
TermTransportLegStats | MediaTransportLegStats | A snapshot of the statistics associated with the terminating transport-leg. The terminating transport-leg (in the context of media proxied via the server) is the leg/segment associated with traffic between the server and the call-terminating party (with respect to the initial call establishment).

See Also

ICallData - Interface


MediaTransportLegStats - Structure

Structure: MediaTransportLegStats

Last Updated: 2014-06-02

This structure is used to contain a snapshot of transfer-statistics for a specific transport “leg” associated with user-plane media data which is proxied through the server application.

Properties:

None

Fields

Field | Type | Description
RtpBytesSent | ulong | The number of RTP bytes proxied over the associated transport leg (in the direction of Server->Client).
RtpBytesReceived | ulong | The number of RTP bytes received over the associated transport leg (in the direction of Client->Server).
RtpPacketsSent | ulong | The number of RTP packets proxied over the associated transport leg (in the direction of Server -> Client).
RtpPacketsReceived | ulong | The number of RTP packets received over the associated transport leg (in the direction of Client->Server).
RtcpBytesSent | ulong | The number of RTCP bytes proxied over the associated transport leg (in the direction of Server -> Client).
RtcpBytesReceived | ulong | The number of RTCP bytes received over the associated transport leg (in the direction of Client->Server).
RtcpPacketsSent | ulong | The number of RTCP packets proxied over the associated transport leg (in the direction of Server -> Client).
RtcpPacketsReceived | ulong | The number of RTCP packets received over the associated transport leg (in the direction of Client->Server).

Notes

  • The statistics provided by this structure are only relevant when user-plane passthrough has been enabled in the server (causing all media-plane traffic to be proxied via the IMS Server application). See SetUserPlanePassthroughState for more information.

  • See the User-Plane_Pass-through_Functionality for a description of the transport-legs and transport-links.

See Also

ICallData - Interface


IClientControl- Interface

Interface: IClientControl

Last Updated: 2014-06-02

This interface to the API enables SIP Server access and control over the current list of registered SIP Clients. The SIP Server may query the list of currently registered clients, select remove, de-register, and re-register any client using the following methods:

Methods:

    • DeRegisterClient

    • IsRegistered

    • RemoveClient

    • ReRegisterClient

    • SelectClient

Properties:

Property | Action | Type | Description
AddressOfRecordAll | [get] | List<string> | List of Client AOR(s) currently registered on the SIP Server. Each Client AOR must be unique.

Notes:

  1. A Client AOR is a unique reference ID used to identify each SIP Client.

  2. The Client AOR is used to target specific clients to check status (Client Registered status), manage connections (Remove/DeRegister client(s)), and send SIP client(s) Messages.

See Also

ICallData - Interface

ICallControl - Interface


DeRegisterClient

Method: DeRegisterClient

bool DeRegisterClient(

[Optional, DefaultParameterValue("")] string AddressOfRecord

);

Forces de-registration of a client using the address of record.

If users are subscribed to the “reg” event associated with the client being de-registered, SIP NOTIFY messages are generated and sent to the relevant subscribers.

Arguments

AddressOfRecord

[in]

The Client AOR to de-register from the SIP Server.

Returns

Possible return values are:

TRUE | The Client (AOR) is available and has been de-registered.
FALSE | The Client (AOR) is not available and/or could not be de-registered.

Notes

Returns True if the Address of Record is available and de-registered successfully, else returns False.

See Also

Interface: IClientControl

AddressOfRecordAll

IsRegistered

ReRegisterClient

SelectClient

RemoveClient


Method: IsRegistered

public bool IsRegistered(

string AddressOfRecord

);

Returns SIP Client registered status from the SIP Server.

Arguments

addressOfRecord

[in]

The Client AOR to query Registered status on the SIP Server.

Returns

Possible return values are:

TRUE | The SIP Client (AOR) is registered with the SIP Server.
FALSE | The SIP Client (AOR) is not registered with the SIP Server.

Notes

Returns True if the Address of Record is registered with the Agilent SIP Server, else returns False. To obtain a list of all SIP Server Client’s AOR list query the property AddressOfRecordAll.

See Also

Interface: IClientControl

RemoveClient

SelectClient


Method: RemoveClient

bool RemoveClient(

[Optional, DefaultParameterValue("")] string AddressOfRecord

);

Removes a client using the address of record.

Arguments

AddressOfRecord

[in]

The Client AOR to remove from the SIP Server.

Returns

Possible return values are:

TRUE | The Client (AOR) is available and has been removed.
FALSE | The Client (AOR) is not removable.

Notes

Returns True if the Address of Record is available and removed, else returns False.

See Also

Interface: IClientControl

AddressOfRecordAll

IsRegistered

SelectClient


ReRegisterClient

Method: ReRegisterClient

bool ReRegisterClient(

[Optional, DefaultParameterValue("")] string AddressOfRecord

);

Forces re-registration of a client using the address of record.

This method causes the Server to shorten the registration period (expiry time) associated with the associated client causing a SIP NOTIFY message to be sent (to any subscribers to the “reg” event associated with the client registration being modified).

If the client associated with the registration period being shortened is subscribed, the reception of the NOTIFY indicating shortened registration time is intended to cause the client to perform a client-initiated SIP re-registration.

Arguments

AddressOfRecord

[in]

The Client AOR on which to perform registration-shorterning.

Returns

Possible return values are:

TRUE | The Client (AOR) is available and the associated registration time has been shortened.
FALSE | The Client (AOR) is not available and/or the registration time could not be shortened.

Notes

Returns True if the Address of Record is available and the registration was shortened successfully, else returns False.

See Also

Interface: IClientControl

AddressOfRecordAll

IsRegistered

DeRegisterClient

SelectClient

RemoveClient


Method: SelectClient

bool SelectClient(string AddressOfRecord);

Selects a client using the address of record.

Arguments

AddressOfRecord

[in]

The Client AOR to select

Returns

Possible return values are:

TRUE | The Client AOR has been selected in the SIP Server application.
FALSE | The Client AOR is not selectable.

See Also

Interface: IClientControl

AddressOfRecordAll

RemoveClient

IsRegistered


IConnection - Interface

Interface: IConnection (Server)

Last Updated: 2014-06-02

This interface to the API provides the connection to the SIP Server application on the local or remote host using the Windows Communication Foundation (WCF) service.

Methods:

  • Close

  • Initialize

Properties

Property | Action | Type | Description
ErrorInformation | [get] | string | Error information. Gets any errors that occurred from the initialize. Read-only property.


Method: Close

Method: Close (Server)

bool Close();

Closes the WCF communication path with the Agilent SIP Server.

Arguments

None

Returns

Possible return values are:

TRUE | The WCF Close was successful.
FALSE | The WCF Close was unsuccessful. Refer to ErrorInformation for additional error information.

Notes

  1. The Close method is called to properly release a previously opened WCF connection.

  2. Once a WCF connection is opened, it must subsequently be explicitly closed by the external application. Otherwise the IMS Server application Local GUI control may not function properly.

See Also

Interface: IConnection

Initialize

ErrorInformation

Version


Method: Initialize

Method: Initialize (IConnection - Server)

bool Initialize(

[Optional, DefaultParameterValue("192.168.1.230")] string Address,

[Optional, DefaultParameterValue(0x2030)] int Port

);

Establishes WCF connection to the Agilent SIP Server API.

Arguments

Address | [in] | URI location of the Agilent SIP Server. Example 192.168.1.230 or localhost. Optional default URI = 192.168.1.230
Port | [in] | Port number for the communications. Optional default port = 8240

Returns

Possible return values are:

TRUE | The WCF Initialization was successful.
FALSE | The WCF Initialization was unsuccessful. Check IConnection: ErrorInformation for additional error information.

Notes

  1. The Agilent SIP Server must be running at the address indicated.

  2. A WCF connection is required to remotely control the SIP Server application. The Initialize method initializes the WCF connection between the controlling application and the SIP Server Application. When the WCF connection is established, the controlling application may send any API methods to control the SIP Server application.

  3. Once a WCF connection is opened, it must subsequently be explicitly closed by the external application. Otherwise the IMS Server application Local GUI control may not function properly.

See Also

Interface: IConnection

Close

ErrorInformation


Interface: ILogging

Last Updated: 2014-06-02

This interface of the Conference-Server provides access to the various logging modules that track various IMS-SIP operations and results.

The various log modules (and API interface) tracked by the Conference-Server include the following:

Error Log – Provides Conference-Server error diagnostics by the following methods:

    • ClearError

    • ReadError

    • SaveError

Status Log - Provides Conference-Server state information and general information by the following methods:

    • ClearStatus

    • ReadStatus

    • SaveStatus

Call-Flow/Detail Log - Provides detailed logging of messages between the conference-server and call participants, by the following methods:

    • ClearDetail

    • SaveDetail

    • StartDetailLog

    • StopDetailLog

In addition the following methods are provided which apply global effects to all logging-modules:

    • ClearAll


Method: ClearAll

public void ClearAll();

Clears the Call Flow, Status, and Error logs.

Arguments

None

Returns

None

Notes

  1. The ClearAll method clears all Logging buffers of data. Log buffers may be cleared individually calling the individual clear functions. The Logging buffers on the SIP Server are: Call Flow, Status, and Error.

  2. The Logging buffers can be cleared while Logging is started or stopped. When a log buffer is stopped, the SIP Server does not fill the buffer with log data. Exceptions to this are the Status Log and Error Log, as these are always running while the SIP Server is activated.

See Also

Interface: ILogging

ClearAll

ClearCallFlow

ClearError

ReadError


Method: ClearCallFlow

public void ClearCallFlow();

Clears the Call Flow Log.

Arguments

None

Returns

None

Notes

  1. The ClearCallFlow method clears the Call Flow Log buffer of data.

  2. The Call Flow Log contains the details on all incoming and outgoing message and responses (Register, SMS and VoIP message and responses). This API method clears both the Call Flow Log and Detail Log data of the graphical user interface.

  3. The Logging buffers may be cleared while Call Flow logging is started or stopped. When the Call Flow logging is stopped, the SIP Server does not fill the Call Flow buffer with log data.

See Also

Interface: ILogging

ClearAll

SaveCallFlow

StartCallFlow

StopCallFlow


Method: ClearError

public void ClearError();

Clears the Error Log.

Arguments

None

Returns

None

Notes

  1. The ClearError method clears the Error Log buffer of data.

  2. The Error Log contains detail on any SIP Server error detected. The detail stored in the Error Log per entry is formatted as follows:

“[“ Timestamp “]” CRLF <log-entry> (CRLF)+

Where (CRLF)+ denotes “at least one” CRLF.

  3. The Error Log buffers can be cleared at any time while the SIP Server is running. Error Logging is always enabled when the SIP Server is activated.

See Also

Interface: ILogging

ClearAll

ReadError

SaveError


ClearStatus (Method)

Method: ClearStatus

public void ClearStatus();

Clears the Status Log.

Arguments

None

Returns

None

Notes

  1. The ClearStatus method clears the Status Log buffer of data.

  2. The Status Log contains informational/diagnostic output details. The detail stored in the Status Log per entry is formatted as follows:

“[“ Timestamp “]” CRLF <log-entry> (CRLF)+

Where (CRLF)+ denotes “at least one” CRLF.

  3. The Status Log buffers can be cleared at any time while the SIP Server is running. Status Logging is always enabled when the SIP Server is activated.

See Also

Interface: ILogging

ClearAll

ReadStatus

SaveStatus


Method: ReadError

public string ReadError();

Returns the SIP Server Error log buffered data.

Arguments

None

Returns

Possible return values are:

String

Error log buffer data

Notes

  1. The Error Log contains the details on any SIP Server error detected. The detail stored in the Error Log per entry is formatted as follows:

“[“ Timestamp “]” CRLF <log-entry> (CRLF)+

Where (CRLF)+ denotes “at least one” CRLF.

  2. The ReadError method reads and returns the current Error Log buffer data. The ReadError method is called to retrieve the current Error Log data for processing. It is recommended that you call this method after each operation is performed within the SIP Server in order to detect any errors. To save the Error Log buffer data to file use the the SaveError method.

  3. The Error Log is always running while the SIP Server is activated, unlike Call Flow log, which must be started and stopped by the API methods.

See Also

Interface: ILogging

ClearAll

ClearError

ReadError

SaveError


ReadStatus

Method: ReadStatus

public string ReadStatus();

Returns the SIP Server Status log buffered data.

Arguments

None

Returns

Possible return values are:

String

Status log buffer data

Notes

  1. The Status Log contains the details on any SIP Server error detected. The detail stored in the Status Log per entry is formatted as follows:

“[“ Timestamp “]” CRLF <log-entry> (CRLF)+

Where (CRLF)+ denotes “at least one” CRLF.

  2. To save the Status Log buffer data to file use the the SaveStatus method.

  3. The Status Log is always running while the SIP Server is activated, unlike Call Flow log, which must be started and stopped by the API methods.

See Also

Interface: ILogging

ClearAll

ClearStatus

SaveStatus


Method: SaveCallFlow

public void SaveCallFlow(

string FileNameAndPath

);

Saves the Call Flow Log buffered data to a specified filename on the SIP Server host machine.

Arguments

FileNameAndPath

[in]

This is the absolute filename and path to which the Call Flow Log is saved on the SIP Server host machine..

Returns

None

Notes

  1. SaveCallFlow saves the current Call Flow Log buffer data to a specified file.

  2. If the file exists, the operation overwrites the existing file contents. If you only specify a filename, the log is saved in the same location as the remote SIP Server Application.

  3. If the path in FileNameAndPath does not exist, an exception is thrown and is caught by the controlling API application.

  4. Logs are saved on the same host as the SIP Server application.

The Call Flow logging must have been stopped prior to attempting to save the log content, otherwise the save will not perform successfully.

See Also

Interface: ILogging

ClearAll

ClearCallFlow

SaveCallFlow

StartCallFlow

StopCallFlow


Method: SaveError

public void SaveError(

string FileNameAndPath

);

Saves the Error log buffered data to a specified filename on the SIP Server host machine.

Arguments

FileNameAndPath

[in]

This is the absolute filename and path to which the Error log is saved on the SIP Server host machine.

Returns

None

Notes

  1. LoggingSaveError saves the current Error Log buffer data to a specified file.

  2. If the file exists, the operation overwrites the existing file contents. If you only specify a filename, the log is saved in the same location as the remote SIP Server Application.

  3. If the path in FileNameAndPath does not exist, an exception is thrown and is caught by the controlling API application.

See Also

Interface: ILogging

ClearAll

ClearError

ReadError

SaveError


SaveStatus

Method: SaveStatus

public void SaveStatus(

string FileNameAndPath

);

Saves the Status Log buffered data to a specified filename on the SIP Server host PC.

Arguments

FileNameAndPath

[in]

This is the absolute filename and path to which the Status Log is saved on the SIP Server host PC.

Returns

None

Notes

  1. Logging SaveStatus saves the current Status Log buffer data to a specified file.

  2. If the file exists, the operation overwrites the existing file contents. If you only specify a filename, the log is saved in the same location as the remote SIP Server Application.

  3. If the path in FileNameAndPath does not exist, an exception is thrown and is caught by the controlling API application.

The Call Flow logging must have been stopped prior to attempting to save the log content, otherwise the save will not perform successfully.

See Also

Interface: ILogging

ClearAll

ClearStatus

ReadStatus


Method: StartCallFlow

public void StartCallFlow();

Starts the SIP Server Call Flow logging module.

Arguments

None

Returns

None

Notes

  1. The Call Flow Log contains the detail on all incoming and outgoing message and response flows (Register, SMS, and VoIP messages and responses). The detail stored (for each log item) in the Call Flow Log is:

“[“AbsoluteTimestamp “]” CRLF

“[Elapsed Time =” RelativeTimestamp “]” CRLF

message-content (CRLF)+

Whereby, RelativeTimestamp is the relative time difference (to millisecond resolution) between log-time of the message compared to the immediately preceeding message, and (CRLF)+ denotes “at least one” CRLF.

  2. StartCallFlow starts the SIP Server Call Flow logging module.

See Also

Interface: ILogging

ClearAll

ClearCallFlow

StopCallFlow


Method: StopCallFlow

public void StopCallFlow();

Stops the SIP Server Call Flow logging module.

Arguments

None

Returns

None

Notes

None

See Also

Interface: ILogging

ClearCallFlow

SaveCallFlow

StartCallFlow

StopCallFlow


Interface: IMessage

Last Updated: 2014-06-02

This interface provides access to configuration and functionality associated with the transfer of messages (both IMS-based MESSAGEs, and legacy 3GPP binary variants).

Methods

  • Send

  • SendDefault3gpp

  • SendDefault3gpp2

  • SendFromFile

Properties

Property | Action | Type | Description
MessageAccountMgr | [get] | IMessageAccountMgr | Provides access to the message-account manager, which is responsible for storing/depositing messages/message-headers. This component is used for the testing of the Message-Waiting-Indication (MWI) functionality.
SmscConfig | [get] | ISmscConfig | Provides access to the configuration/parameters associated with the Short-Message Service-Centre (SMSC), associated with legacy 3GPP messaging.


Method: Send

bool Send(

MessageType MessageType,

string SMSMessage,

bool SendMessageAsHex,

[Optional, DefaultParameterValue("")] string AddressOfRecord

);

Sends a message to a client.

Arguments

messageType | [in] | Message type of the message to send
message | [in] | Message to send

Returns

Possible return values are:

TRUE | Send method successfully sent message.
FALSE | Send method failed to send message (for more error information see ReadError and related methods).

Notes

The Send method sends a specified SMS message of type 3gpp, 3gpp2, or Plain Text to a registered SIP client (AddressOfRecord). The message can be optionally flagged as Hex data. If the message is set as Hex data, the string message contents must contain Hex characters only. If the AddressOfRecord is not provided, a client must be selected using the Method: SelectClient function.

See Also

Interface: IMessage

AddressOfRecordAll

MessageType

SendDefault3gpp

SendDefault3gpp2

SendFromFile

ReadError


Method: SendDefault3gpp

bool SendDefault3gpp(

[Optional, DefaultParameterValue("")] string AddressOfRecord

);

Sends a 3gpp default formatted SMS message to a registered SIP Client which is located here:

  • For Windows XP:
    C:\Documents and Settings\All Users\Documents\Agilent\IMS-SIP Server\DataFiles\ImsSipServerSettings.xml

  • For Windows 7:
    C:\Users\Public\Documents\Agilent\IMS-SIP Server\DataFiles\ImsSipServerSettings.xml

Arguments

AddressOfRecord

[in]

Target Client AOR where you wish to send message.

Returns

Possible return values are:

TRUE | Default 3gpp SMS successfully sent.
FALSE | Default 3gpp SMS failed to send successfully (for more error information see ReadError and related methods).

Notes

The MessageSendDefault3gpp method sends a pre-formatted SMS message of type 3gpp to a registered SIP client (AddressOfRecord). The message is sent as Hex data. If the AddressOfRecord is not provided, a client must be selected using the SelectClient method.

See Also

Interface: IMessage

AddressOfRecordAll

Send Interface: IMessage

Send

SendDefault3gpp2

SendFromFile


Method: SendDefault3gpp2

bool SendDefault3gpp2(

[Optional, DefaultParameterValue("")] string AddressOfRecord

);

Sends a pre-formatted specified 3gpp2 SMS message from the SIP Server to a registered SIP Client which is located here:

  • For Windows XP:
    C:\Documents and Settings\All Users\Documents\Agilent\IMS-SIP Server\DataFiles\ImsSipServerSettings.xml

  • For Windows 7:
    C:\Users\Public\Documents\Agilent\IMS-SIP Server\DataFiles\ImsSipServerSettings.xml

Arguments

AddressOfRecord

[in]

Target Client AOR for which you wish to send message.

Returns

Possible return values are:

TRUE | Default 3gpp2 SMS successfully sent.
FALSE | Default 3gpp2 SMS failed to send successfully (for more error information see ReadError and related methods).

Notes

SendDefault3gpp2 sends a pre-formatted SMS message of type 3gpp2 to a registered SIP client AddressOfRecord). The message is sent as Hex data. If the AddressOfRecord is not provided, a client must be selected using the SelectClient method.

See Also

IMessage

Send

SendDefault3gpp

SendFromFile

AddressOfRecordAll


Method: SendFromFile

bool SendFromFile(

MessageType MessageType,

string FileNameAndPath,

[Optional, DefaultParameterValue("")] string AddressOfRecord

);

Sends a message from file to a specified SIP Client.

Arguments

MessageType | [in] | The type of message you wish to send.
FileNameAndPath | [in] | Absolute file path name of the SMS contents to send.
AddressOfRecord | [in] | Target Client AOR for which you wish to send message.

Returns

Possible return values are:

TRUE | SMS successfully sent.
FALSE | SMS failed to send successfully (for more error information see ReadError and related methods).

Notes

SendFromFile sends a pre-formatted SMS message of type 3gpp, 3gpp2, or Plain Text to a registered SIP client (AddressOfRecord). The message is sent from a specified file by the SIP Server. The message contents in the specified file should match the type specified. If the function returns FALSE the ReadError method should be queried to get the error message.

See Also

IMessage

IClientControl

AddressOfRecordAll

SendFromFile

MessageType

SendDefault3gpp

SendDefault3gpp2

Send


Interface: IMessageAccountData

Last Updated: 2014-06-02

This interface provides access to the state associated with a particular message account.

Methods

None

Properties

Property | Action | Type | Description
AccountId | [get] | string | An id-string which uniquely identifies this message account.
AssociatedUserIdList | [get/set] | List<string> | The list of URI values who are associated/mapped to this message-account.
MwiMessageInfoList | [get/set] | List<MwiMessageInfoStruct> | The list of deposited messages currently waiting in this message-account. Note: if the content of this list is changed (and those changes are applied/committed back to the message-account manager), this will cause MWI notifications to be sent to the users associated with this message-account).

See Also

IMessageAccountMgr


Interface: IMessageAccountMgr

Last Updated: 2014-06-02

This interface provides access to the message-account manager.

The message-account manager is responsible for adding/removing and maintaining message-accounts, where each account is responsible for tracking deposited/cached messages associated with one (or more) users.

The Message-Waiting-Indication (MWI) functionality can be invoked and tested by dynamically modifying the content of these message accounts.

Methods

  • CreateAccount

  • DeleteAccountById

  • DeleteAllAccounts

  • GetAllAccountIds

  • GetAccountDataById

  • SaveMessageAccountData

  • LoadMessageAccountData

  • ApplyAccountChanges

Properties

None

See Also

How to Create Message Accounts


Method: AddCustomResponse

Last Updated: 2014-06-02

string AddCustomResponse(string response);

Add the specified SIP response message to the custom-response list. (Note: only SIP responses with an "unsuccessful" status-code are allowed – i.e. provisional/successful responses must not be provided )

Arguments

response

[in]

The SIP response message formatted as per RFC3261 (and associated IETF RFCs)

Note that substitution-tokens can be used within the defined content to provide a mechanism to dynamically populate certain parts of the response (dialog-tags, branch-identifers etc..)

For more information on the use of substitution-tokens, refer to Substitution-Tokens in the topic How to Create Custom Error Responses

Returns

Possible return values are:

ID (string) | Returned if the operation to add the custom response message is successful. A unique ID string-value associated with the custom-response entry that was added. .
Null | Returned if the operation failed. (More error information may be available in the “Error Log”. See ReadError and related methods for more details.

See Also

ReadError

How to Create Custom Error Responses


Method: ModifyCustomResponseById

Last Updated: 2014-06-02

bool ModifyCustomResponseById(string existing_id, string new_response);

Replaces the existing custom SIP message (identified by “id”) with the specified new custom message content.

Arguments

existing_id

[in]

The unique ID string-value associated with the previously added custom-message that is to be modified.

new_response

[in]

The replacement SIP response message formatted as per RFC3261 (and associated IETF RFCs)

Note that substitution-tokens can be used within the defined content to provide a mechanism to dynamically populate certain parts of the response (dialog-tags, branch-identifers etc..)

For more information on the use of substitution-tokens, refer to Substitution-Tokens in the topic How to Create Custom Error Responses

Returns

Possible return values are:

True | bool | The operation succeeded. The custom-response message content associated with the specified ID has been successfully modified.
False | bool | The operation failed. (More error information may be available in the “Error Log”. See ReadError and related methods).

Notes

The ID associated with the custom-message entry does not change as a result of perform this modification procedure, only the content associated with the ID is changed.

See Also

ReadError

How to Create Custom Error Responses


Method: RemoveCustomResponseById

bool RemoveCustomResponseById (string id);

Removes the existing custom SIP message associated with the specified ID.

Arguments

id

[in]

ID associated with the current custom SIP response message you wish to remove.

Returns

Possible return values are:

True | bool | The unique ID value (string) associated with the custom-message entry that is to be removed .
False | bool | The operation failed. (More error information may be available in the “Error Log”. See ReadError and related methods).


Method: RemoveAllCustomResponses

void RemoveAllCustomResponses();

Clears the custom-response list, removing/deleting all previously configured custom SIP response messages/strings.

Arguments

None

Returns

None


Method: LoadCustomResponseData

bool LoadCustomResponseData(string filename);

Loads the custom-response data from the specified file.

Arguments

filename

[in]

The (fully path-qualified) file to load.

Returns

Possible return values are:

True | bool | The data was loaded successfully from the specified file.
False | bool | The data was not loaded successfully from the specified file. (for more error information see ReadError and related methods).


Method: SaveCustomResponseData

bool SaveCustomResponseData (string filename);

Saves the currently configured custom-response data to the specified file.

Arguments

filename

[in]

The (fully path-qualified) file to save .

Returns

Possible return values are:

True | bool | The operation succeeded. The custom-response data was saved to the specified file.
False | bool | The operation failed. (more error information may be available in the “Error Log”. See ReadError and related methods).

See Also

ReadError


Method: CreateAccount

IMessageAccountData CreateAccount();

Creates a new message-account, initialized to default-content and adds it into the Message-Account manager.

Arguments

None

Returns

Possible return values are:

IMessageAccountData

Returned if a new message-account was successfully added – contains the message-account data of the newly created message-account.

The data contains a unique read-only “accountId” value which is used to uniquely identify this message-account when making changes to the account-data.

For example, with this return-value, the default-content can be modified (ex: changing the “AssociatedUserIdList” of the account, and then this can be applied back to the message-account manager, by calling ApplyAccountChanges() of the manager (and specifying the unique-id of the message-account).

Null

Returned if a new message-account could not be created/added to the message-account manager.


Method: DeleteAccountById

bool DeleteAccountById (string accountId);

Removes the existing message account (identified by “id”). Returns a Boolean indicating whether the operation succeeded.

Arguments

accountId

[in]

ID associated with the message account you wish to remove.

Returns

Possible return values are:

True | bool | The message account, indicated by the ID, was successful deleted.
False | bool | The message account, indicated by the ID, was not successful deleted. (for more error information see ReadError and related methods).

Notes

Removing a message-account may result in the generation/transmission of SIP NOTIFY messages from the server indicating the change to any users that are associated with the deleted message-account (and are also subscribed to the “message-summary” event).

See Also

ReadError


Method: DeleteAllAccounts

void DeleteAllAccounts ();

Removes/deletes all message-accounts from the message-account manager.

Arguments

None

Returns

None

Notes

The removal of message-accounts may result in the generation/transmission of SIP NOTIFY messages from the server indicating the change to any users that are associated with the deleted message-accounts (and are also subscribed to the “message-summary” event).


Method: GetAllAccountIds

List<string> GetAllAccountIds();

Queries the message-account manager for a list of the account-ids of all message-accounts which exist within the manager (i.e. which may have been previously created/added/loaded).

Arguments

None

Returns

Possible return values are:

Account-IDs

List<string>

A list of the account-ids for all message accounts which currently exist in the account-manager.


Method: GetAccountDataById

IMessageAccountData GetAccountDataById (string accountId);

Retrieves the current data/state of the message-account (associated with the specified account-id) from the message-account manager.

Arguments

accountId

[in]

The (unique) ID identifying the message-account for which data/state is requested.

Returns

Possible return values are:

Account-data

IMessageAccountData

Returns (a copy of) the current state of the message-account associated with the specified account-id.


Method: SaveMessageAccountData

bool SaveMessageAccountData (string filename);

Saves the currently configuration/state of the message-account manager (including message-account data) to the specified file.

Arguments

filename

[in]

The (fully path-qualified) file to save.

Returns

Possible return values are:

True | bool | The operation succeeded. The message-account data was saved to the specified file.
False | bool | The operation failed. (More error information may be available in the “Error Log”. See ReadError and related methods).

See Also

ReadError


Method: LoadMessageAccountData

bool LoadMessageAccountData (string filename);

Loads the message-account data from the specified file.

Arguments

filename

[in]

The (fully path-qualified) message-account-data file to load.

Returns

Possible return values are:

True | bool | The data was loaded successfully from the specified file.
False | bool | The data was not loaded successfully from the specified file. (for more error information see ReadError and related methods).

See Also

ReadError


Method: ApplyAccountChanges

bool ApplyAccountChanges (string accountId, IMessageAccount newAccountData);

Replaces account data in the existing message account (identified by “id”) with the specified new account data. Returns a Boolean indicating whether the operation succeeded.

Arguments

accountId | [in] | The unique ID string-value of the previously configured message-account you wish to modify.
newAccountData | [in] | The replacement message-account data.

Returns

Possible return values are:

True | bool | The message account data, indicated by the ID, was successfully modified and saved.
False | bool | The message account data, indicated by the ID, was not successfully modified and saved. (for more error information see ReadError and related methods).

Notes

Changes to account data may result in the generation/transmission of SIP NOTIFY messages from the server indicating the changes to any users that are associated with the modified message-account (and are also subscribed to the “message-summary” event).

See Also

ReadError


IServer - Interface

Interface: IServer

Last Updated: 2014-06-02

This interface to the API enables Server control. Server Control methods provide the ability to start/stop the Server and query the Server version.

Methods:

  • Start

  • StopListeners

  • LoadConfigurationData

  • SaveConfigurationData

  • GetValidListeners

  • GetActiveListeners

  • SetActiveListeners

  • GetValidNics

  • GetActiveNic

  • SetActiveNic

  • SetActivePort

  • GetRecentConfigurations

Properties:

Property | Action | Type | Description
Version | [get] | string | Returns the version of SIP Server. Read-only property.
ServerRunning | [get] | bool | Returns a boolean indicating whether the application is current in a started/running state or not. Read-only property.


Method: Start

bool Start()

Attempts to change the server state to active/started.

  • If the server is active/started, it is capable of receiving and processing incoming SIP control-plane signalling messages (on the addresses/ports configured in the application).

  • If the server is inactive/stopped, it will not receive or process any SIP control-plane messages.

Arguments

None

Returns

Possible return values are:

TRUE | The server has been started successfully (or was already in an active/started state).
FALSE | The server failed to change to a started/active state. The error log may contain more details of the failure.

Notes

The Start method Starts the SIP Server to the start-up state. Starting the SIP Server clears any currently registered Clients, requiring the SIP Clients to re-register.

See Also

IServer


Method: StopListeners

void StopListeners();

Stops the SIP Server.

Arguments

None

Returns

None

Notes

StopListeners stops the SIP Server running and terminates all communication with any SIP Clients.

See Also

Interface: IServer

Start

Version


Method: LoadConfigurationData

bool LoadConfigurationData(string filename);

Loads configuration data from a previously saved configuration file.

Arguments

string

The file (including fully-qualified path) to load.

Returns

Possible return values are:

TRUE | The configuration file was successfully loaded.
FALSE | The configuration file failed to load correctly.

See Also

IServer


Method: SaveConfigurationData

bool SaveConfigurationData(string filename);

Saves the current application-configuration to a specified file.

Arguments

filename

[in]

The file (including fully-qualified path) which should store the configuration data.

Returns

Possible return values are:

TRUE | The configuration was saved successfully to the specified file.
FALSE | The configuration failed to save correctly.

Notes

The saved configuration does not currently store the state associated with the following functions:

  • Custom SIP Error Responses

  • Filtering Configuration.

See Also

IServer


Method: GetValidListeners

List<IpAddrInfoStruct> GetValidListeners();

Queries the list of all valid IP-addresses which can be configured as active listeners within the application.

Arguments

None

Returns

Possible return values are:

List<IpAddrInfoStruct>

A list of entries providing information on each of possible/valid

IP-addresses which can be configured as active listener addresses within the application. The content of this list is based on the underlying network configuration of the system.

Notes

If the underlying network configuration of the system is changed (ex: network interfaces are enabled/disabled) whilst the application is running, the application must be restarted, otherwise the network-information available within the application shall be stale/incorrect.

See Also

IServer


Method: GetActiveListeners

List<IpAddrInfoStruct> GetActiveListeners();

Provides information of the IP-addresses which are configured for the reception of SIP control-plane messaging in the application. If the application is in a “started” state, all of these addresses shall be capable of receiving inbound data.

Arguments

None

Returns

Possible return values are:

List<IpAddrInfoStruct>

A list of entries providing information on each of the configured IP-addresses.

Notes

If the underlying network configuration of the system is changed (ex: network interfaces are enabled/disabled) whilst the application is running, the application must be restarted, otherwise the network-information available within the application shall be stale/incorrect.

See Also

IServer


Method: SetActiveListeners

bool SetActiveListeners(string commaSeparatedIpAddresses);

Allows configuration of the IP-addresses that are configured for the reception of SIP control-plane messaging in the application. If the application is in a “started” state, all of the “active” addresses shall be capable of receiving inbound data.

Arguments

commaSeperatedIpAddresses

[in]

A string containing a comma-seperated list of IP-addresses to configure as the active-listener addresses.

The address-values specified must all be recognized as valid listener addresses (as queried from GetValidListeners()) for this operation to work successfully.

An example value might be: “192.168.1.1, 192.168.1.2”

Returns

Possible return values are:

TRUE | The specified IP-addresses have been successfully configured as active listener addresses.
FALSE | A problem occurred when attempting to change the active listener IP-addresses.

Notes

  • If the underlying network configuration of the system is changed (ex: network interfaces are enabled/disabled) whilst the application is running, the application must be restarted, otherwise the network-information available within the application shall be stale/incorrect.

  • It is recommended that application is changed to a “stopped” state, prior to reconfiguring the active listener list.

See Also

IServer


Method: GetValidNics

List<string> GetValidNics();

Queries the names of all valid network-interfaces which are available to application.

Arguments

None

Returns

Possible return values are:

List<string>

A list of the names of all valid network-interfaces available to application

This can be used, for example, when determining the name of an interface to specify when setting the active transmission interface via SetActiveNic().

Notes

If the underlying network configuration of the system is changed (ex: network interfaces are enabled/disabled) whilst the application is running, the application must be restarted, otherwise the network-information available within the application shall be stale/incorrect.

See Also

IServer


Method: GetActiveNic

string GetActiveNic()

Queries the network-interface (NIC) adapter name that is currently configured for outbound/transmit purposes.

Arguments

None

Returns

Possible return values are:

string

The user-friendly name (as representing the operating system) of the network adapter configured for SIP outbound/transmit purposes.

Notes

If the underlying network configuration of the system is changed (ex: network interfaces are enabled/disabled) whilst the application is running, the application must be restarted, otherwise the network-information available within the application shall be stale/incorrect.

See Also

IServer

StopListeners


Method: SetActiveNic

bool SetActiveNic (string networkInterfaceName)

Configures the network-interface (NIC) adapter (associated with the specified interface-name) that is currently configured for outbound/transmit purposes.”

Arguments

networkInterfaceName

[in]

The user-friendly name (as representing the operating system) of the network adapter configured for SIP outbound/transmit purposes.

The specified value/name must be a recognized value as returned by GetValidNics() for this operation to complete successfully.

Returns

Possible return values are:

TRUE | The active (transmission) network-interface has been changed successfully.
FALSE | A problem occurred when attempting to change the active network-interface.

Notes

  • If the underlying network configuration of the system is changed (ex: network interfaces are enabled/disabled) whilst the application is running, the application must be restarted, otherwise the network-information available within the application shall be stale/incorrect.

  • It is recommended that application is changed to a “stopped” state, prior to reconfiguring the active network-interface.

See Also

IServer


Method: SetActivePort

bool SetActivePort([Optional, DefaultParameterValue(5060)] uint16 Port)

Allows configuration of the port-number associated with the reception of SIP control-plane signalling.

Arguments

Port

[in]

Sets the active port used for reception of SIP control-plane signalling.

The optional/default value is 5060

Returns

Possible return values are:

TRUE | The port was successfully reconfigured.
FALSE | Reconfiguration of the active port was unsuccessful.

See Also

IServer


Method: GetRecentConfigurations

List<string> GetRecentConfigurations();

Queries the list of recently-used configuration files loaded/saved within the application.

Arguments

None

Returns

Possible return values are:

List<string>

The list of filenames that are currently in the “recent configurations” list of the application.

See Also

IServer


Interface: ISignaling

Last Updated: 2014-06-02

This interface on the SIP Server enables access to all incoming SIP Signaling Protocol message and response header field values. The SIP Signaling Protocol message/responses are broken into two categories: Registration and Request (Non-Registration). Registration protocol message/responses are all message/responses relating to the SIP Registration process. Request (Non-Registration) SIP Signaling Protocol messages are all message/responses that are not registration related (for example: SMS and VoIP).

Methods:

  • RegistrationClear

  • RegistrationIsFeatureTagSupported

  • RequestClear

Properties:

Property | Action | Type | Description
RegistrationAllow | [get] | string | Allow header parameter from the Registration message.
RegistrationAuthorization | [get] | string | Authorization header parameter from the Registration message
RegistrationContact | [get] | string | Contact header parameter from the Registration message
RegistrationCSeq | [get] | string | CSeq header parameter from the Registration message
RegistrationExpire | [get] | string | Expire header parameter from the Registration message.
RegistrationFrom | [get] | string | From header parameter from the Registration message
RegistrationTo | [get] | string | To header parameter from the Registration message
RequestAllow | [get] | string | Allow header parameter from the last received request message
RequestContact | [get] | string | Contact header parameter from the last received request message
RequestContentLength | [get] | string | ContentLength header parameter from the last received request message
RequestContentType | [get] | string | Content type header parameter from the last received request message
RequestCSeq | [get] | string | CSeq header parameter from the last received request message
RequestExpire | [get] | string | Expire header parameter from the last received request message
RequestFrom | [get] | string | From header parameter from the last received request message
RequestTo | [get] | string | To header parameter from the last received request message
RequestType | [get] | string | Type header parameter from the last received request message


Method: RegistrationClear

public void RegistrationClear();

Clears the Registration Signaling Protocol buffer on the SIP Server.

Arguments

None

Returns

None

Notes

RegistrationClear clears the Signaling Registration buffered data on the SIP Server. The properties cleared are:

  • RegistrationAllow

  • RegistrationAuthorization

  • RegistrationContact

  • RegistrationCSeq

  • RegistrationExpire

  • RegistrationFrom

  • RegistrationTo

See Also

Interface: ISignaling

RegistrationIsFeatureTagSupported

RequestClear


Method: RegistrationIsFeatureTagSupported

bool RegistrationIsFeatureTagSupported(

string FeatureTag

);

Queries the Contact Header of the last received SIP REGISTER message for an indication of support for a particular feature-tag.

Arguments

FeatureTag

[in]

SIP supported-feature tag.

Returns

Possible return values are:

TRUE | The last received SIP REGISTER message indicates support for the specified feature-tag.
FALSE | The last received SIP REGISTER message does not indicate support for the specified feature-tag.

Notes

RegistrationIsFeatureTagSupported returns True if the Feature Tag is contained in the contact string in the last registration, otherwise returns False.

See Also

Interface: ISignaling

RegistrationClear

RequestClear

RegistrationAllow

RegistrationAuthorization

RegistrationContact

RegistrationCSeq

RegistrationExpire

RegistrationFrom

RegistrationTo


Method: RequestClear

void RequestClear();

Clears the request signaling protocol buffer on the SIP Server.

Arguments

None

Returns

None

Notes

RequestClear clears the Signalling Registration buffered data on the SIP Server.

See Also

Interface: ISignaling

RegistrationIsFeatureTagSupported

RequestClear

RegistrationAllow

RegistrationAuthorization

RegistrationContact

RegistrationCSeq

RegistrationExpire

RegistrationFrom

RegistrationTo


ISignalingControl - interface

Interface: ISignalingControl

Last Updated: 2014-06-02

This interface on the SIP Server is used to modify various SIP-Signaling related controls.

Methods:

None

Properties:

Property | Action | Type | Description
ApplyStrictSipRequestHeaderValidation | [get/set] | bool | Modifies whether the server applies strict validation of the Headers contained in received SIP Requests. In particular, this parameter controls whether Requests which do not contain Mandatory headers are rejected.
ControlPlaneConfig | [get] | IControlPlaneConfig | Provides access to an interface enabling modification of control-plane configuration (such as message-filtering).
E911Config | [get] | IE911Config | Provides access to an interface enabling modification of emergency-service configuration.
EnableRingingResponse | [get/set] | bool | Modifies whether the server generates an implicit "180 RINGING" during initial call-establishment INVITE processing.
IncludeRecordRoute | [get/set] | bool | Modifies whether Record-Route header is included by Server in Requests which initiate a Dialog (for example: INVITE).
RegistrationMaxExpires | [get/set] | uint | Specifies the maximum "Expires:" value associated with incoming registration requests. If a client or UAC requests a larger value, the Expires value in the SIP OK response is reduced or capped to this value.
SendOversizedSipRequestsViaTcp | [get/set] | bool | Modifies whether over-sized SIP Requests intended to be proxied over a UDP transport should instead be proxied via TCP. Note that "over-sized" is determined as per the guidelines in RFC 3261 (as in, based on UDP MTU size.
UserPlaneConfig | [get] | IUserPlaneConfig | Provides access to an interface enabling modification of user-plane configuration (such as data-filtering).


IControlPlaneConfig - interface

Interface: IControlPlaneConfig

Last Updated: 2014-06-02

This interface on the SIP Server enables SIP Control-Plane configuration .

Methods:

None

Properties:

Property | Action | Type | Description
ControlPlaneFilterMgr | [get] | IControlPlaneFilterMgr | Provides access to an interface enabling management of filtering on the control plane.

See Also

SIP Control-Plane API Filtering-Rule Specification

SIP User-Plane API Filtering-Rule Specification


IControlPlaneFilterMgr - interface

Interface: IControlPlaneFilterMgr

Last Updated: 2014-06-02

This interface on the SIP Server enables SIP Control-Plane configuration.

Methods:

None

Properties:

Property | Action | Type | Description
FilterMgr_UAC | [get] | IFilterMgr | Provides access to an interface enabling filtering between the Server and UAC.
FilterMgr_UAS | [get] | IFilterMgr | Provides access to an interface enabling filtering between the Server and UAS.

Notes:

The diagram below shows the logical placement of the control-plane filtering cores.

See Also

IControlPlaneConfig - interface

SIP Control-Plane API Filtering-Rule Specification

SIP User-Plane API Filtering-Rule Specification


IUserPlaneConfig - interface

Interface: IUserPlaneConfig

Last Updated: 2014-06-02

This interface on the SIP Server provides access to the User-Plane configuration.

Methods:

SetUserPlanePassthroughState

Properties:

Property | Action | Type | Description
FilterMgr_UP | [get] | IFilterMgr | Enables configuration of the user-plane filtering capability in the Server.

Notes:

User-plane filtering rules which are configured via FilterMgr_UP only apply if user-plane passthrough is enabled (via SetUserPlanePassthroughState).

See Also

SIP User-Plane API Filtering-Rule Specification

SIP Control-Plane API Filtering-Rule Specification

IFilterMgr - interface

IControlPlaneConfig

IControlPlaneFilterMgr


SetUserPlanePassthroughState (Method)

Method: SetUserPlanePassthroughState

bool SetUserPlanePassthroughState(bool enabled);

This method enables or disables the underlying Media-Proxy Core within the User-Plane filtering core. In addition, it ultimately enables or disables whether user-plane traffic is routed through Server during VoIP sessions.

Arguments

enabled

[in]

Boolean specifying whether to enable or disable the Media-Proxy core for user-plane traffic.

Returns

TRUE: | State is successfully applied.
FALSE: | State failed to be applied.

Notes:

The user-plane passthrough state can only be modified when the Server is in a "stopped" state.

See Also

IUserPlaneConfig

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


IFilterMgr - interface

Interface: IFilterMgr

Last Updated: 2014-06-02

This interface on the SIP Server encapsulates the publicly-accessible (common) members of the various filtering-cores provided in the application.

Methods:

  • AddFilterRule

  • GetFilterRuleById

  • GetFilterRuleByIndex

  • GetTriggerCounterById

  • GetTriggerCounterByIndex

  • ModifyFilterRuleById

  • RemoveAllFilterRules

  • RemoveFilterRuleById

  • ResetAllTriggerCounters

  • ResetTriggerCountersById

  • ResetTriggerCountersByIndex

Properties:

None

See Also

IUserPlaneConfig

IControlPlaneFilterMgr

SIP Control-Plane API Filtering-Rule Specification

SIP User-Plane API Filtering-Rule Specification


AddFilterRule (Method)

Method: AddFilterRule

int AddFilterRule(string ruleString);

Adds a new filter rule to the filter-core.

Arguments

The formatted rule-string to be added.

For more information, see SIP Control-Plane API Filtering-Rule Specification and SIP User-Plane API Filtering-Rule Specification.

Returns

An integer value representing the "id" associated with the rule.

Notes

A returned “id” value which is negative indicates that an error occurred when attempting to add the new filter rule.

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


GetFilterRuleById (Method)

Method: GetFilterRuleById

string GetFilterRuleById(int id);

Gets the filtering rule-string associated with the rule (within the rule-set) identified by a specified ID.

Arguments

id

[in]

The ID value of the rule to retrieve (which was acquired during the previous addition of the filter-rule).

Returns

Possible return values are:

<string> | The rule-string associated with the requested rule_ID.
null | The rule with the specified ID could not be located.

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


GetFilterRuleByIndex (Method)

Method: GetFilterRuleByIndex

string GetFilterRuleByIndex(int index);

Gets the filtering rule-string associated with the rule (within the rule-set) at the specified index.

Arguments

index

[in]

The index of the rule in the rule-set table to retrieve.

Returns

Possible return values are:

<string> | The rule-string associated with the requested index.
null | The rule-string associated with the requested index is invalid.

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


GetTriggerCounterById (Method)

Method: GetTriggerCounterById

int GetTriggerCounterById(int Id);

Gets the number of times the rule (specified by ID) has been matched or triggered.

Arguments

Id

[in]

The ID value of the rule to examine.

Returns

<non-negative integer> | The number of trigger-occurrences or matches associated with the rule identified by the specified rule-ID.
<negative integer> | The rule cannot be located.

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


GetTriggerCounterByIndex (Method)

Method: GetTriggerCounterByIndex

int GetTriggerCounterByIndex(int Index);

Gets the number of times the rule (specified by index in the rule-set) has been matched/triggered .

Arguments

Index

[in]

The index of the rule in the rule-set table.

Returns

<non-negative integer> | The number of trigger-occurrences or matches associated with the rule identified by the specified rule-ID.
<negative integer> | The rule cannot be located.

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


ModifyFilterRuleById (Method)

Method: ModifyFilterRuleById

bool ModifyFilterRuleById(int existing_id, string newRuleString);

Modifies or substitutes an existing rule entry with a new rule-string.

Arguments

existing_id | [in] | The rule-ID associated with the rule being modified or replaced (as returned by a previous AddFilterRule).
newRuleString | [in] | The new rule-string to apply to the filter-rule identified by existing_id.

Returns

Possible return values are:

TRUE | Association or replacement of the filter-rule was successful.
FALSE | Association failed (for example, a rule with the specified ID could not be found, or the new rule-string syntax is invalid.

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


RemoveAllFilterRules (Method)

Method: RemoveAllFilterRules

void RemoveAllFilterRules();

Removes all rules currently configured in the associated filter-core.

Arguments

None

Returns

None

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


RemoveFilterRuleById (Method)

Method: RemoveFilterRuleById

bool RemoveFilterRuleById(int id);

Removes a filter-rule which is identified by the rule-ID value.

Arguments

id

[in]

The ID value of the rule to find and remove.

Returns

Possible return values are:

TRUE | Removal of ID was successful.
FALSE | removal of ID failed.

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


ResetAllTriggerCounters (Method)

Method: ResetAllTriggerCounters

void ResetAllTriggerCounters();

Resets the trigger-counts associated with all rules in the rule-set associated with the filtering-core.

Arguments

None

Returns

None

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


ResetAllTriggerCountersById (Method)

Method: ResetAllTriggerCountersById

bool ResetTriggerCounterById(int id);

Resets the trigger-counter for the rule specified by the rule-ID provided.

Arguments

id

[in]

The ID value of the rule to process.

Returns

TRUE | Rule was found and trigger-counter was reset successfully.
FALSE | Rule was not found and trigger-counter reset failed.

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


ResetAllTriggerCountersByIndex (Method)

Method: ResetAllTriggerCountersByIndex

bool ResetTriggerCounterByIndex(int id);

Resets the trigger-counter for the specified rule (identified by an index in the rule-set).

Arguments

index

[in]

The index of the rule in the rule-set table.

Returns

TRUE | Rule was found and trigger-counter was reset successfully.
FALSE | Rule was not found and trigger-counter reset failed.

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


IE911Config - interface

Interface: IE911Config

Last Updated: 2014-06-02

This interface on the SIP Server enables SIP Control-Plane configuration .

Methods:

  • GetSipUriForServiceType

  • SetSipUriForServiceType

Properties:

Property | Action | Type | Description
AllowAnonymousEmergencyReqs | [get/set] | bool | Controls whether anonymous emergency-session requests are accepted or rejected by the Server.
AllowEmergencyReqistrations | [get/set] | bool | Controls whether the Server accepts or rejects attempts to register emergency contacts.
AllowEmergencyReqsInNormalReg | [get/set] | bool | Controls whether emergency-session requests over a non-emergency registration or contact are accepted or rejected by the Server .
AllowNormalReqsInEmergencyReg | [get/set] | bool | Controls whether non-emergency request attempts over an emergency registration or contact are accepted or rejected by the Server .
AllowUnmarkedEmergencyReg | [get/set] | bool | Controls whether unmarked emergency-session requests are accepted or rejected by the Server.
ProvideAssertedIdentity | [get/set] | bool | Controls whether the emergency-service URN is made visible in the P-Asserted-Identity header of requests or responses originating from the emergency-service endpoint during session-related signaling.
RegistrationMaxExpires | [get/set] | uint | Specifies the maximum "Expires:" value associated with incoming emergency-registration requests. If a client or UAC requests a larger value, the Expires value in the SIP OK response is reduced or capped to this value.


GetSipUriForServiceType (Method)

Method: GetSipUriForServiceType

string GetSipUriForServiceType(AgSipEmergencyServiceType serviceType);

Enables retrieval of the current URI which is associated with a particular emergency-service type (as in that associated to an emergency-service URN).

Arguments

serviceType

[in]

The emergency-service type for which the associated URI mapping is requested.

Returns

Possible return values are:

<string> | The associated or mapped URI.
null | No URI value is mapped to the specified emergency-service type.

See Also

IE911Config

IControlPlaneConfig

IControlPlaneFilterMgr


SetSipUriForServiceType (Method)

Method: SetSipUriForServiceType

void SetSipUriForServiceType(AgSipEmergencyServiceType serviceType, string uri);

Enables modification of the URI associated with a particular emergency-service type.

Arguments

serviceType | [in] | The emergency-service type to which the specified URI should be associated.
uri | [in] | The URI value to associate with the specified emergency-service type.

Returns

None.

See Also

IE911Config

IControlPlaneConfig

IControlPlaneFilterMgr


ISubscriptionManager - Interface

Interface: ISubscriptionManager

Last Updated: 2014-06-02

This interface on the SIP Server is used to configure or modify the active user(s) subscription-data.

Methods:

  • AddNewSubscription

  • ApplySubscriptionChanges

  • DuplicateExistingSubscription

  • GetSubscriptionData

  • LoadSubscriberData

  • RemoveSubscription

  • SaveSubscriberData

Properties:

None

See Also

ISubscription


AddNewSubscription (Method)

Method: AddNewSubscription

ISubscription AddNewSubscription(string defaultUserId);

Adds a new (default-valued) subscription entry into the (active) Subscriber Database.

Arguments

None

Returns

Possible return values are:

ISubscription | A reference to the newly added subscription .
Null | If the new subscription is not created or added successfully, then Null is returned.

See Also

ISubscriptionManager


ApplySubscriptionChanges (Method)

Method: ApplySubscriptionChanges

bool ApplySubscriptionChanges(string defaultUserId, ISubscription newSubscriptionData);

Apply/Commit Subscriber-Data modifications back into the active Subscriber Database for the specified user (AssertedId).

Arguments

defaultUserId | [in] | The default/asserted-id identifying the subscription to be modified.
newSubscriptionData | [in] | The new subscription data to associate or apply to the subscription associated with the subscription identified by defaultUserId.

Returns

Possible return values are:

TRUE | The changes were applied successfully.
FALSE | T he changes were not applied successfully, or the specified subscription record could not be found.

See Also

ISubscriptionManager


DuplicateExistingSubscription (Method)

Method: DuplicateExistingSubscription

ISubscription DuplicateExistingSubscription(string originalId, string newId);

Add a (deep) copy/duplicate subscription entry into the (active) Subscriber Database.

Arguments

originalId | [in] | The Asserted-ID associated with the source or original subscription to be copied. The Asserted-ID is considered the "key" value that uniquely identifies subscriber-records).
newId | [in] | The Asserted-ID value to be associated with the new copy of the source subscriber-data..

Returns

Possible return values are:

ISubscription | Returns a reference to the newly duplicated subscription entry if successful.
Null | If the duplication fails, Null is returned.

See Also

ISubscriptionManager


GetSebscriptionData

Method: GetSubscriptionData

ISubscription GetSubscriptionData(string defaultUserId);

Returns a reference to a (deep) copy of the subscription data associated with the provided AssertedId.

Arguments

defaultUserId

[in]

The Asserted-ID associated with the subscription-data to be retrieved.

Returns

Possible return values are:

ISubscription | Returns a reference to the subscription entry if successful.
Null | If there are no subscription entries, Null is returned.

See Also

ISubscriptionManager


LoadSubscriberData (Method)

Method: LoadSubscriberData

bool LoadSubscriberData(string filename);

Loads the subscriber-data from the specified file.

Arguments

filename

[in]

The name of the subscriber-data file to load.

Returns

Possible return values are:

TRUE | The subscriber-data file was loaded successfully.
FALSE | The specified file could not be found, contained incorrectly formatted data, or failed to load due to some other error.

See Also

ISubscriptionManager


RemoveSubscription

Method: RemoveSubscription

bool RemoveSubscription(string defaultUserId);

Removes the subscriber-data associated with the specified AssertedId from the active Subscriber Database.

Arguments

defaultUserId

[in]

The Asserted-ID associated with the subscription to be removed.

Returns

Possible return values are:

TRUE | Indicates that the entry was found and successfully removed.
False | Indicates the entry was not found and removed.

See Also

ISubscriptionManager


SaveSubscriberData

Method: SaveSubscriberData

bool SaveSubscriberData(string filename);

Saves the currently active Subscriber Database content to the specified file.

Arguments

filename

[in]

The filename to use for saving the current subscriber-information.

Returns

Possible return values are:

TRUE | The operation completed successfully.
FALSE | The operation failed.

See Also

ISubscriptionManager


ISubscription - Interface

Interface: ISubscription

Last Updated: 2014-06-02

This interface on the SIP Server provides access to subscriber-specific parameters associated with an individual subscriber.

Methods:

None

Properties:

Property

Action

Type

Description

AssertedId

[get/set]

string

Set or get AssertedId.

AssociatedUserIdList

[get/set]

List<string>

Set or get the list of associated URIs.

SuppServiceConfig

[get/set]

 SupplementaryServiceStruct

Set or Get the supplementary service configuration associated with the subscriber.

MSISDN

[get/set]

string (digit-string)

Sets/gets the MSISDN associated with the subscriber-profile. This value is used when correlation between legacy identifier (MSISDN) to an IMS identifier is required (for example when processing legacy 3GPP binary SMS messages).

SpecialSms3gppMwiIndicationEnabled

[get/set]

bool

Sets/gets the configuration of whether the “Special SMS Message Indication” mechanism (outlined in section 9.2.3.24.2 of 3GPP 24.030) is used for this subscriber (for the purposes of indicating waiting messages).

If enabled, the mechanism is invoked when a user associated with this subscriber-profile performs successful IMS registration.

SecurityConfig

[get/set]

 SecurityConfigStruct

Sets/gets the security profile/configuration associated with this subscriber – for example, whether authentication is required/enabled etc...


SecAuthConfigStruct

Structure: SecAuthConfigStruct

Last Updated: 2014-06-02

This structure, available in the Server API, encapsulates the authentication component of an IMS security configuration.

Properties:

Property | Action | Type | Description
AKA_Algorithm | [set/get] | AuthAkaAlgorithmType | Set or get the AKA-specific authentication algorithm to be used in the comparison (only applies when AuthAlgorithm is “AKA”).
AKA_ResLength | [set/get] | unsigned integer | Configures the length (in bytes) of the RES value to use during AKA authentication. Valid range is 4-16.
AKA_K | [set/get] | string | Specifies the K value to use as (one of) the input values to the Authentication algorithm. Note: This string must only be composed of precisely 32 hex-characters.
AKA_OpType | [set/get] | AuthOpType | Specifies whether the value in the OP property is treated as an OP or an OPc value-type.
AKA_OpValue | [set/get] | string | Specifies the OP/OPc value to use as (one of) the input values to the Authentication algorithm. Note: This string must only be composed of precisely 32 hex-characters.
AKA_Rand | [set/get] | string | Specifies the RAND value to use as (one of) the input values to the Authentication algorithm. Note: This string must only be composed of precisely 32 hex-characters.
AKA_Amf | [set/get] | string | Specifies the Authentication Management Field (AMF) value to use as (one of ) the input values to the Authentication algorithm. Note: This string value must only be composed of precisely 4 hex-characters.
AuthRealm | [set/get] | string | Specifies both the realm input-value for Authentication algorithm calculations, and also the domain/realm associated and controlled by the Server application, which is used during URI resolution. For example: when converting from a TEL URI.
AuthAlgorithm | [set/get] | AuthAlgorithmType | Specifies the SIP Server Authentication algorithm used when performing Authentication procedures. May be set to one of these AuthAlgorithmTypes: AKAv1, AKAv2, or MD5.
EnableAuthentication | [set/get] | bool | Configures whether or not Authentication procedures are enabled (and required by the Server).
MD5_Username | [set/get] | string | Specifies the username string to use during MD5 authentication procedures.
MD5_Password | [set/get] | string | Specifies the password string to use during MD5 authentication procedures.

Fields

None

See Also

ISubscription - Interface

SupplementaryServiceStruct


SecIpsecConfigStruct

Structure: SecIpsecConfigStruct

Last Updated: 2014-06-02

This structure, available in the Server API, encapsulates the IPsec component of an IMS security configuration.

Properties:

Property | Action | Type | Description
IntegrityAlgo | [set/get] | IPsecIntegrityAlgEnum | The IPsec integrity algorithm associated with the configuration.
EncryptionAlgo | [set/get] | IPsecEncryptionAlgEnum | The IPsec encryption algorithm associated with the configuration.

Fields

None

See Also


SupplementaryServiceStruct

Structure: SupplementaryServiceStruct

Last Updated: 2014-06-02

This structure, available in the Server API, provides access to various supplementary-service configurations associated with each subscription.

Properties:

None

Fields

Field | Type | Description
OipConfig | SuppServConfig_OipStruct | The “Originating-Identity Presentation” configuration. (outlined in 3GPP TS 24.607)
OirConfig | SuppServConfig_OirStruct | The “Originating-Identity Restriction” configuration (outlined in 3GPP TS 24.607)
TipConfig | SuppServConfig_TipStruct | The “Terminating-Identity Presentation” configuration (outlined in 3GPP TS 24.608)
TirConfig | SuppServConfig_TirStruct | The “Originating-Identity Restriction” configuration (outlined in 3GPP TS 24.608)
NdubConfig | SuppServConfig_NdubStruct | The “Network-Detected User Busy” configuration, utilized for network/server-detected busy conditions of target/peer clients.
CwConfig | SuppServConfig_CwStruct | The “Communication-Waiting” configuration (outlined in 3GPP TS 24.615).

See Also

ISubscription


SuppServConfig_CwStruct

Structure: SuppServConfig_CwStruct

Last Updated: 2014-06-02

This structure, available in the Server API, provides access to the “Communication Waiting” supplementary-service configuration parameters (3GPP TS 24.615).

Properties:

Property

Action

Type

Description

ConfigurationEnabled

[set/get]

bool

High-level enable/disable of the supplementary-service.

  • If this is set to false (i.e., the configuration is disabled), the associated subscriber-profile is configured to behave as though there is no record/profile present for the associated supplementary-service. To further clarify, this is treated as though the supplementary-service profile does not exist (e.g., as though it were deleted via XCAP etc..), and all other settings for the supplementary-service are ignored.

  • If this is set to true, the supplementary-service configuration shall be enabled, and the behaviour shall be based on the other service-specific settings available.

Active

[set/get]

SSEnum_ActiveState

Denotes the “active” status of the CW service.

Tascw_duration

[set/get]

uint32

Specifies the duration associated with Timer Tascw (in seconds).

Currently the valid range is: 30-120 (inclusive).

This timer is outlined in 3GPP TS 24.615.

Fields

None


SuppServConfig_NdubStruct

Structure: SuppServConfig_NdubStruct

Last Updated: 2014-06-02

This structure, available in the Server API, provides access to the criteria associated with “Network-Detected User-Busy” functionality.

Properties:

Property | Action | Type | Description
MaxConcurrentSessions | [set/get] | UInt32 | Specifies the criteria (in terms of concurrent-session count) that the intended target of a session-establishment may have before the server considers the target to be “busy”. The current valid range is 1-10 (inclusive).

Fields

None

See Also

ISubscription - Interface

SupplementaryServiceStruct


SuppServConfig_OipStruct

Structure: SuppServConfig_OipStruct

Last Updated: 2014-06-02

This structure, available in the Server API, provides access to the “Originating-Identity Presentation” supplementary-service configuration parameters (3GPP TS 24.607).

Properties:

Property

Action

Type

Description

Active

[get/set]

SSEnum_ActiveState

Denotes the "active" status of the OIP service.

ConfigurationEnabled

[get/set]

bool

High-level enable/disable of the supplementary-service.

  • If this is set to false (i.e., the configuration is disabled), the associated subscriber-profile is configured to behave as though there is no record/profile present for the associated supplementary-service. To further clarify, this is treated as though the supplementary-service profile does not exist (e.g., as though it were deleted via XCAP etc..), and all other settings for the supplementary-service are ignored.

  • If this is set to true, the supplementary-service configuration shall be enabled, and the behaviour shall be based on the other service-specific settings available.

Fields

None

See Also

ISubscription - Interface

SupplementaryServiceStruct


SuppServConfig_OirStruct

Structure: SuppServConfig_OirStruct

Last Updated: 2014-06-02

This structure, available in the Server API, provides access to the "Originating-Identity Restriction" supplementary-service configuration parameters (3GPP TS 24.607).

Properties:

Property

Action

Type

Description

Active

[get/set]

SSEnum_ActiveState

The “active” status of the OIR service which applies when the “Mode” is configured to “temporary”. .

Mode

[get/set]

SSEnum_IDRestrictionMode

The restriction-mode of the OIR service.

RestrictionType

[get/set]

SSEnum_IDRestrictionType

The level of ID restriction/anonymization associated with the OIR service (when the service is applied).

TemporaryMode

[get/set]

SSEnum_IDRestrictionTempMode

The temporary-mode of the OIR service which applies if the “Mode” is configured to “temporary”.

ConfigurationEnabled

[get/set]

bool

High-level enable/disable of the supplementary-service.

  • If this is set to false (i.e., the configuration is disabled), the associated subscriber-profile is configured to behave as though there is no record/profile present for the associated supplementary-service. To further clarify, this is treated as though the supplementary-service profile does not exist (e.g., as though it were deleted via XCAP etc..), and all other settings for the supplementary-service are ignored.

  • If this is set to true, the supplementary-service configuration shall be enabled, and the behaviour shall be based on the other service-specific settings available.

Fields

None

See Also

ISubscription

SupplementaryServiceStruct


SuppServConfig_TipStruct

Structure: SuppServConfig_TipStruct

Last Updated: 2014-06-02

This structure, available in the Server API, provides access to the “Terminating-Identity Presentation” supplementary-service configuration parameters (3GPP TS 24.608).

Properties:

Property

Action

Type

Description

Active

[get/set]

SSEnum_ActiveState

Denotes the “active” status of the TIP service.

ConfigurationEnabled

[get/set]

bool

High-level enable/disable of the supplementary-service.

  • If this is set to false (i.e., the configuration is disabled), the associated subscriber-profile is configured to behave as though there is no record/profile present for the associated supplementary-service. To further clarify, this is treated as though the supplementary-service profile does not exist (e.g., as though it were deleted via XCAP etc..), and all other settings for the supplementary-service are ignored.

  • If this is set to true, the supplementary-service configuration shall be enabled, and the behaviour shall be based on the other service-specific settings available.

Fields

None

See Also

ISubscription - Interface

SupplementaryServiceStruct


SuppServConfig_TirStruct

Structure: SuppServConfig_TirStruct

Last Updated: 2014-06-02

This structure, available in the Server API, provides access to the “Terminating-Identity Restriction” supplementary-service configuration parameters (3GPP TS 24.608).

Properties:

Property

Action

Type

Description

Active

[set/get]

SSEnum_ActiveState

The "active" status of the TIR service which applies when the "Mode" is configured to "temporary".

Mode

[set/get]

SSEnum_IDRestrictionMode

The restriction-mode of the TIR service.

TemporaryMode

[set/get]

SSEnum_IDRestrictionTempMode

The temporary-mode of the TIR service which applies if the “Mode” is configured to “temporary”.

ConfigurationEnabled

[get/set]

bool

High-level enable/disable of the supplementary-service.

  • If this is set to false (i.e., the configuration is disabled), the associated subscriber-profile is configured to behave as though there is no record/profile present for the associated supplementary-service. To further clarify, this is treated as though the supplementary-service profile does not exist (e.g., as though it were deleted via XCAP etc..), and all other settings for the supplementary-service are ignored.

  • If this is set to true, the supplementary-service configuration shall be enabled, and the behaviour shall be based on the other service-specific settings available.

Fields

None

See Also

ISubscription - Interface

SupplementaryServiceStruct


SecurityConfigStruct

Structure: SecurityConfigStruct

Last Updated: 2014-06-02

This structure, available in the Server API, encapsulates the security-configuration associated with a subscriber.

Properties:

Property | Action | Type | Description
AuthConfig | [set/get] | SecAuthConfigStruct | The authentication component of the security configuration.
IpsSecConfig | [set/get] | SecIpsecConfigStruct | The IPsec component of the security configuration.

Fields

None

See Also

ISubscription - Interface

SupplementaryServiceStruct


Reference of Enumerated Types (Server)

Last Updated: 2014-06-02

This topic provides a reference for all enumerated types defined for the E6966B IMS-SIP API Server Emulator Software.

Server

  • AgSipEmergencyServiceType

  • AltRespMessageType

  • AuthAkaAlgorithmType

  • AuthAlgorithmType

  • AuthComparisonType

  • AuthOpType

  • CallSessionState

  • IPSecIntegrityAlgEnum

  • MediaTransferStateEnum

  • MessageType

  • SSEnum_ActiveState

  • SSEnum_IDRestrictionMode

  • SSEnum_IDRestrictionTempMode

  • SSEnum_IDRestrictionType

See Also

Alphabetical List of API Methods (Server)

Alphabetical List of Structures (Server)

Interfaces by Category-Server


Enumerated Type: AgSipEmergencyServiceType

public enum AgSipEmergencyServiceType

{

Unspecified = 1,

None = 0,

Ambulance = 2,

FireBrigade = 3,

Police = 4,

MarineGuard = 5,

MountainRescue = 6,

}

Field Description

This enumeration is used to identify a specific type of IMS emergency-service.

Value | Comment
Unspecified | This value is used for method return-values where a valid associated service-type could not be found.
None | Denotes a generic emergency-service associated with "<urn:service:sos>" (outlined in RFC 5031).
Ambulance | Denotes the emergency-service associated with the "<urn:service:sos.ambulance>" (outlined in RFC 5031).
FireBrigade | Denotes the emergency-service associated with the "<urn:service:sos.fire>" (outlined in RFC 5031).
Police | Denotes the emergency-service associated with the "<urn:service:sos.police>" (outlined in RFC 5031).
MarineGuard | Denotes the emergency-service associated with the "<urn:service:sos.marine>" (outlined in RFC 5031).
MountainRescue | Denotes the emergency-service associated with the "<urn:service:sos.mountain>" (outlined in RFC 5031).

See Also

IE911Config


Enumerated Type: AltRespMessageType

public enum AltRespMessageType

{

Ok (Normal) = 1,

None = 0,

Accepted = 2,

BadRequest = 3,

Forbidden = 4,

NotFound = 5,

Request Timeout = 6,

ServerError = 7,

BadGateway = 8,

ServiceUnavailable = 9

}

Field Description

AltRespMessageType contains the SIP Server alternative response types. Any of the types can be used to configure the SIP Server to response to all incoming SIP messages with that alternative response.

The following alternative response values with descriptions of operation are defined:

Value | Comment
OK | SIP Server responds to all incoming messages with Response = OK
None | SIP Server does not respond to any incoming SIP messages. This field value should be used to test UE/DUT SIP Client message time-outs
Accepted | SIP Server responds with an Accepted message.
Bad Request | SIP Server responds to all incoming SIP messages with Response = 400 Bad Request
Forbidden | SIP Server responds to all incoming SIP messages with Response = 403 Forbidden
Not Found | SIP Server responds to all incoming SIP messages with Response = 404 Not Found
Request Timeout | SIP Server responds to all incoming SIP messages with Response = Request Timeout
ServerError | SIP Server responds to all incoming SIP messages with Response = 500 Server Error
BadGateway | SIP Server responds to all incoming SIP messages with Response = 502 Bad Gateway
ServiceUnavailable | SIP Server responds to all incoming SIP messages with Response = 503 Service Unavailable

See Also

Interface: IAlternateResponse


Enumerated Type: AuthAkaAlgorithmType

public enum AuthAkaAlgorithmType

{

DummyXor = 0,

Milenage = 1

}

Field Description

AuthAkaAlgorithmType contains the supported SIP Server AKA-specific authentication algorithm types. The types listed may be used to configure the SIP Server AKA-specific authentication algorithm type to apply to all incoming SIP registrations.

The following AKA-specific authentication algorithms supported with descriptions are defined:

Value | Comment
DummyXor | Denotes the 3GPP TS 34.108 dummy/Xor algorithm.
Milenage | Denotes the Milenage algorithm.

See Also

IAuthentication

AlgorithmType


Enumerated Type: AuthAlgorithmType

public enum AuthAlgorithmType

{

MD5,

AKAv1

AKAv2

}

Field Description

AuthAlgorithmType contains the supported SIP Server authentication algorithm types. The types listed may be used to configure the SIP Server authentication algorithm type to apply to all incoming SIP registrations.

The following authentication algorithms supported with descriptions are defined:

Value | Comment
MD5 | Uses MD5 Message-Digest Algorithm
AKAv1 | Uses Authentication and Key Agreement (AKA) version 1
AKAv2 | Uses Authentication and Key Agreement (AKA) version 2

See Also

Interface:IAuthentication

AlgorithmType


Enumerated Type: AuthComparisonType

public enum AuthComparisonType

{

ResponseComparison = 0,

AlwaysFail = 1

}

Field Description

AuthComparisonType defines the types of Authentication comparisons the SIP Server supports. The types are used to configure the SIP Server with the desired authentication processing on the comparison routine.

The following alternative response values with descriptions of operation are defined:

Value | Comment
Always Fail | Results in SIP Client Registration attempts failing authentication with Unauthorized response. The SIP Server fails the authenticating comparison process automatically for all incoming Registration requests when authentication is enabled.
ResponseComparison | The SIP Server processes the authenticating comparison routine normally.

See Also

Interface:IAuthentication


Enumerated Type: AuthOpType

public enum AuthOpType

{

OP,

OPc

}

Field Description

AuthOpType defines the authentication OP types. These are used to configure the SIP Server with the desired OP or OPc values.

If OPc type and value requires configuring on the SIP Server for authentication, the IAuthentication: OpType property is set to type OPc. This enables the OPc property value to be configured using the property IAuthentication:OP.

The following OP Key Option values are defined:

Value | Comment
OP | A 128-bit Operator Variant Algorithm Configuration Field
OPc | A 128-bit value derived from OP and K

See Also

Interface:IAuthentication


Enumerated Type: CallSessionState

public enum CallSessionState

{

Trying = 0,

Ringing = 1,

CallHeld = 2,

Cancelling = 3,

AwaitingCallHeldAck = 4,

AwaitingAck = 5,

Connected = 6,

Updating = 7,

UpdatingToHold = 8,

Ending = 9,

Ended = 10,

Waiting = 11,

}

Field Description

CallSessionState denotes the specific call-state of a particular call/session.

The following states are defined:

Value | Comment
Trying | The call is currently in a “Trying” state (i.e. has not processed any non-100 provisional responses yet)
Ringing | The call is currently “Ringing” (having processed a 180 Ringing response)
CallHeld | The call is currently in a call-held state.
Cancelling | An initial call-setup is in the process of being cancelled (having received a CANCEL request).
AwaitingCallHeldAck | The call is transitioning to a call-held state, but is awaiting the final ACK.
AwaitingAck | The call is transitioning to an active state, but it still awaiting the final ACK.
Connected | The call is established in an active (i.e. non-held) state.
Updating | An established call is in the process of being updated (due to reception of an UPDATE/re-INVITE)
UpdatingToHold | An established call is in the process of being updated to a call-hold state (due to an UPDATE/re-INVITE)
Ending | The call is in the process of terminating.
Ended | The call has been terminated.
Waiting | The call-setup request has invoked/triggered the Communicating Waiting supplementary-service procedure and is currently in a “Waiting” state.

See Also

Authentication


Enumerated Type: IPsecEncryptionAlgEnum

public enum IPsecEncryptionAlgEnum

{

Des_Ede3_Cbc = 0,

Aes_Cbc = 1,

Null = 2

}

Field Description

IPsecEncryptionAlgEnum identifies a specific IPsec encryption-algorithm type.

The following values are defined:

Value | Comment
Des_Ede3_Cbc | Denotes the Triple-DES (3DES) Cipher block chaining (CBC) encryption algorithm.
Aes_Cbc | Denotes the AES Cipher block chaining (CBC) encryption algorithm.
Null | Denotes a null (plaintext) ciphering algorithm.

Notes

3GPP TS 33.203 provides more information regarding the IP-based security mechanisms employed for IMS.


Enumerated Type: IPsecIntegrityAlgEnum

public enum IPsecIntegrityAlgEnum

{

Hmac_Md5_96 = 0,

Hmac_Sha_1_96 = 1

}

Field Description

IPsecIntegrityAlgEnum identifies a specific IPsec integrity-algorithm type.

The following values are defined:

Value | Comment
HmacMd5_96 | Denotes the integrity algorithm described by RFC2403
HmacSha1_96 | Denotes the integrity algorithm described by RFC2404


Enumerated Type: MediaTransferStateEnum

public enum MediaTransferState

{

Inactive = 0,

RecvOnly = 2,

SendOnly = 1,

SendRecv = 3,

}

Field Description

MediaTransferState contains the SIP Server media transfer states.

The following media transfer state values with descriptions are defined:

Value | Comment
Inactive | There is no media transfer.
RecvOnly | Media is only received.
SendOnly | Media is only sent.
SendRecv | Media can be sent and received.


Enumerated Type: MessageContextEnum

public enum MessageContextEnum

{

None = 0,

Voice = 1,

Video = 2,

Fax = 3,

Pager = 4,

Multimedia = 5,

Text = 6

}

Field Description

MessageContextEnum specifies the “message-context” associated with a particular message.

Message Contexts are outlined in RFC 3458.

The following values are defined:

Value | Comment
None | Denotes an unspecified message-context.
Voice | Denotes a message-context of “voice”.
Video | Denotes a message-context of “video”.
Fax | Denotes a message-context of “fax”.
Pager | Denotes a message-context of “pager”.
Multimedia | Denotes a message-context of “multimedia”.
Text | Denotes a message-context of “text”.


Enumerated Type: MessagePriorityEnum

public enum MessagePriorityEnum

{

Normal = 0,

NonUrgent = 1,

Urgent = 2,

}

Field Description

MessageContextEnum specifies the “message priority” associated with a particular message.

Message priority is outlined in RFC 4021.

The following values are defined:

Value | Comment
Normal | Denotes a message priority of “normal”.
NonUrgent | Denotes a message priority of “non-urgent”.
NonUrgent | Denotes a message priority of “urgent”.


Enumerated Type: MessageType

public enum MessageType

{

PlainText,

Gpp,

Gpp2

}

Field Description

MessageType defines the types of SMS message type formats supported by the SIP Server for sending SMS messages.

The following field values with descriptions are defined:

Value | Comment
Gpp | 3gpp SMS message type format
Gpp2 | 3gpp2 SMS message type format
PlainText | Plain Text SMS message type format

See Also:

Interface: IMessage

Send

SendFromFile


Enumerated Type: SSEnum_ActiveState

public enum SSEnum_ActiveState

{

False = 0,

True = 1,

Default = 2,

}

Field Description

SSEnum_ActiveState denotes the activation-state of a supplementary-service, and correlates to the “active” attribute of the XML-element defined in the XML-Schema for a particular supplementary-service.

The top-level XCAP schema outlines the “active” attribute of the “simservType” as:

<xs:attribute name="active" type="xs:boolean" use="optional" default="true"/>

The following values are defined:

Value | Comment
False | Specifies that the associated supplementary service shall be configured with the “active” attribute set to “false”.
True | Specifies that the associated supplementary service shall be configured with the “active” attribute set to “true”
Default | Specifies that the associated supplementary service shall be configured with the “active” attribute unspecified. (which, as outlined in the schema definition above, functionally defaults to “true”).

See Also


Enumerated Type: SSEnum_IDRestrictionMode

public enum SSEnum_IDRestrictionMode

{

Permanent = 1,

Temporary = 0,

}

Field Description

SSEnum_IDRestrictionMode denotes a (Caller) ID-restriction mode, for use with the OIR/TIR supplementary services.

Value | Comment
Permanent | specifies that the associated ID-restriction service is "always on".
Temporary | specifies that the associated ID-restriction service is determined by additional criteria or settings associated with the service.

See Also

IE911Config


Enumerated Type: SSEnum_IDRestrictionTempMode

public enum SSEnum_IDRestrictionTempMode

{

Default=2,

PresNotRestricted = 1,

PresRestricted = 0,

}

Field Description

SSEnum_IDRestrictionTempMode denotes the temporary (Caller) ID-restriction mode, for use with the OIR/TIR supplementary services.

Value | Comment
PresNotRestricted | Specifies that ID-restriction shall not be applied (inactive).
PresRestricted | Specifies that ID-restriction shall not be applied (inactive).
Default | Specifies that the application of ID-restriction shall be dictated by the default state (outlined in the 3GPP specification) that is associated with the specific supplementary-service to which the value is applied.

Notes

The temporary ID-restriction mode only applies when the (non-temporary) ID-restriction mode is set to "temporary". Furthermore, if the (non-temporary) ID-restriction mode is set to "permanent", this overrules the temporary ID-restriction mode.

See Also

IE911Config


Enumerated Type: SSEnum_IDRestrictionType

public enum SSEnum_IDRestrictionType

{

RestrictAllPrivateHeaderInfo = 1,

RestrictAssertedIdentity = 0,

}

Field Description

SSEnum_IDRestrictionType denotes the level of ID-restriction which is applied to any identities which are selected for restriction.

Value | Comment
RestrictAllPrivateHeaderInfo | Specifies that several identity-headers are removed or are made anonymous when performing ID-restriction.
RestrictAssertedIdentity | Specifies that only the "P-Asserted-Identity" header is removed from proxied messages.

See Also

IE911Config


Understanding API Filtering

Programming Examples and Other Reference Material (Server)

Last Updated: 2014-06-02

For programming examples and other related information, see these topics below:

  • Example API Usage (Server)

  • SIP Request/Response (Control-Plane) RUI Filtering-Rule Specification

  • SIP User-Plane API Filtering-Rule Specification


Control-Plane API Filtering-Rule Specification

SIP Control-Plane API Filtering-Rule Specification

Last Updated: 2014-06-02

This section outlines the expected format of the rule-string provided when adding a filtering-rule using the API for control-plane filtering.

If a rule-string value supplied to an API method is not well-formed, the corresponding API methods return an appropriate failure (or error value) and the active rule-set is not modified.

The definition is specified in ABNF notation as follows (where CPFiltRule specifies the aggregated rule-string supplied to the API methods). Note that the ABNF notation is defined in [RFC 5234].

This topic contains the following sections:

  • Control-plane_Filtering-Rule_ABNF_Description

  • Examples_of_Control-plane_Filtering

Control-plane Filtering-Rule ABNF Description

; [Begin] Control-Plane Filtering-Rule ABNF description

EQ = [WSP] “=” [WSP]

FiltURI = addr-spec / “*”

SrcURI = “from-uri” EQ FiltURI

DestURI = “request-uri” EQ FiltURI

FiltCustomResponseAction = “custom_response:” [WSP] “id” [WSP] “=” [WSP] 1*DIGIT

FiltDelayAction = “delay:” [WSP] 1*DIGIT [“ms”]

FiltDiscardAction = “discard”

FiltNoAction = “none”

CPFiltActionType = (FiltDelayAction / FiltDiscardAction / FiltNoAction / FiltCustomResponseAction)

FiltAction = “action” EQ (FiltDelayAction / FiltDiscardAction / FiltNoAction)

CPReqVal = 1*ALPHA

CPRespVal = 1*ALPHA / ( 1*DIGIT [“ “ 1*ALPHA] )

CPReqValParams = ( CPReqVal [“;” CPReqValParams] ) / “*”

CPRespValParams = ( CPRespVal [“;” CPRespValParams] ) / “*”

CPReqOrResp = (“request” EQ CPReqValParams) / (“response” EQ CPRespValParams)

CPFiltCriteria = SrcURI CRLF DestURI CRLF CPReqOrResp [CRLF “[in-dialog-only]”] /

[CRLF (“[server-associated]” / “[peer-to-peer]“) ] /

[CRLF (“[indicate-when-triggered]”

CPFiltAction = “action” EQ 1CPFiltActionType

CPFiltRule = 1CPFiltCriteria 2CRLF 1CPFiltAction CRLF

; [End] Control-Plane Filtering-Rule ABNF description

Note: the following ABNF definitions are defined elsewhere:

CRLF ; defined in RFC 2234.

DIGIT ; defined in RFC 2234.

WSP ; white-space (as defined in RFC 2234).

addr-spec ; defined in s25.1 of RFC 3261.

Examples of Control-plane Filtering

Example 1: Delaying 180 RINGING response for 10 seconds

The following filter-definition specifies that for calls originating from client1@agilent.com to client2@agilent.com, the RINGING provisional-response returned by client2 during call-setup is delayed by 10 seconds:

Filter Definition

From–uri = sip:client@agilent.com

request–uri = sip:client2@agilent.com

response = RINGING

action = delay: 10000ms

Example 2: Blocking re-INVITEs

The following filter-definition specifies that for in-dialog INVITES (i.e., re-INVITES) originated from client2@agilent.com, the request is discarded by the server when received from client2 (instead of being forwarded/proxied to peer client) regardless of the target/peer URI.

Filter Definition

From–uri = sip:client2@agilent.com

request–uri = *

request = INVITE

[in-dialog-only]

[indicate-when-triggered]

action = discard

Example 3: Delaying server-initiated RINGING response by 300ms

The following filter-definition specifies for calls originating from client1@agilent.com to client2@agilent.com, (assuming server-initiated RINGING response is enabled), the server-initiated RINGING shall be delayed by 300ms. Note that this only affects the server-initiated RINGING response, and if client2@agilent.com sends a peer-to-peer RINGING response the filter-rule will not be triggered for that case.

Filter Definition

From–uri = sip:client1@agilent.com

request–uri = sip:client2@agilent.com

respone = RINGING

[server-associated]

action = delay: 300ms

Example 4: Custom response to INVITE Request

The following filter-definition specifies that for in-dialog INVITES (i.e. re-INVITES) originated from client2@agilent.com, the server shall return the custom SIP response associated with the custom-response-id value of 53512.

Filter Definition

From–uri = sip:client2@agilent.com

request–uri = *

request = INVITE

[in-dialog-only]

action = custom_response: id=53512

Note that for this rule to perform as expected, there must be a custom-response message configured in the server (and that is identified by the id-value specified in the filter-rule here – i.e. an id of 53512).

For additional information regarding custom-response functionality, refer to How to Create Custom Error Responses and Control-Plane Filtering Overview.

See Also

SIP User-Plane API Filtering-Rule Specification

IUserPlaneConfig - interface

IFilterMgr - interface


User-Plane Filtering Overview

Last Updated: 2014-06-02

The following diagrams and text outline the general User-Plane (UP) filtering design in the IMS-SIP Server application.

User-Plane Pass-through Functionality

The server application provides the ability to cause all user-plane traffic to be redirected or proxied via the server, instead of directly, peer-to-peer, between the VoIP client endpoints.

When pass-through is enabled, the IP Address and port information within the SDP that is contained in control-plane messages, which establish or reconfigure VoIP sessions, are rewritten as it passes through the server. This causes the client endpoints to target the user-plane traffic (RTP and RTCP) via the Server.

When this pass-through or redirection is active within the server, it allows the server to perform statistics-tracking and filtering of the traffic as it passes through.

What Does Pass-through Involve?

When media is being proxied through the server (due to UP pass-through), the high-level outline is similar to the example below which involves a VoIP session between Clients A and B:

The VoIP session can contain multiple streams of different media-types, which are referred to as TransportLinks in the IMS-SIP Server.

In the example above, if we expand the detail of the VoIP session between clients A and B, from the server perspective, it looks like this:

Each transport-link (for example: media-stream) utilizes (at least one) RTP/RTCP stream-pair, for transferring the user-plane traffic associated with the media-type.

The server, acting as a “man in the middle” of the user-plane traffic, treats the communication between itself and each of the clients associated with the VoIP session as belonging to different TransportLegs.

The leg/hop between the server and the initial call-originator of the VoIP session is termed the OriginatingTransportLeg.

The leg/hop between the server and the initial call-terminator of the VoIP session is termed the TerminatingTransportLeg.

Note that the “initial call-originator” refers to the Client that sent the initial INVITE, and “initial call terminator” refers to the target client receiving the initial INVITE. Since these terms only apply to the initial call-setup (and not any future reconfiguration of the call) the designation of the OriginatingTransportLeg and TerminatingTransportLeg is fixed or anchored for the duration of the call, regardless of any future session reconfiguration.

This is shown diagrammatically below for our example between Client A and B:

  • The assumption in the diagram below is that Client A sent the initial INVITE).

  • Only the “audio” TransportLink from this example is shown below. A similar structure applies to all other media-types/TransportLink(s) associated with the VoIP session.

Individual Transport Link Matching Details

As previously mentioned, the above diagram shows the ports or connectivity associated with a single TransportLink. Often a VoIP session may contain more than one media-type (and therefore multiple TransportLinks), and thus would utilize this kind of relationship for each TransportLink associated with the active session.

Notice that the designation of “TX” and “RX” is from the perspective of the server, as in “TX” designates transfer in the direction of server to client-endpoint, and “RX” designates transfer in the direction of client-endpoint to server.

This distinction becomes clear when analyzing the session-statistics while performing user-plane filtering of the traffic.

Consider the example, where a user-plane filter is applied to block or discard all RTP traffic from Client A to Client B. When Client A transmits RTP frames to the Server, the OriginatingTransportLeg RTP RX statistics increase for the transport-link, but the RTP TX statistics of the associated TerminatingTransportLeg will not increase (since the payload is dropped at the server due to filtering).

See Also

AddFilterRule (Method)

Programming Examples and Other Reference Material

Example_API_Usage__Server


User-Plane API Filtering-Rule Specification

SIP User-Plane API Filtering-Rule Specification

Last Updated: 2014-06-02

This section outlines the expected format of the rule-string provided when adding a filtering-rule using the API for user-plane filtering (for example: RTP/RTCP).

If a rule-string value supplied to an API method is not well-formed, the corresponding API methods return an appropriate failure (or error value) and the active rule-set is not modified.

The definition is specified in ABNF notation as follows (where UPFiltRule specifies the aggregated rule-string to be supplied to API methods).

  1. In the context of the user-plane filtering rules, SrcURI and DestURI essentially denote the initial originating and terminating party of a call, respectively. In addition, the roles of the originating-party and the terminating-party are “locked-down” or anchored for the duration of the call (constituted by the original dialog identifier tuple of <from-tag, to-tag, and call-ID> ) regardless of whether re-INVITES or UPDATEs are performed by either peer-client.

  2. For ABNF rules used here which are not explicitly defined as part of this section, see “SIP Control-Plane API Filtering-Rule Specification” for the definitions.

This topic contains the following sections:

  • User-Plane_Filtering-Rule_ABNF_Description

  • Examples_of_User-Plane_Filtering

User-Plane Filtering-Rule ABNF Description

; [Begin] User-Plane Filtering-Rule ABNF description

UPProt = “protocol” EQ (“rtp” / “rtcp” / “*”)

UPDirection = “direction” EQ (“tx” / “rx” / “*”)

UPFiltCriteria = SrcURI CRLF DestURI CRLF UPProt CRLF UPDirection

UPFiltRule = 1UPFiltCriteria 2CRLF 1FiltAction CRLF

; [End] User-Plane Filtering-Rule ABNF description

Examples of User-Plane Filtering

Example 1

The following pair of filter definitions discard all RTP traffic from client1 to client2 (regardless of the call-originator) for calls between client1@agilent.com and client2@agilent.com.

Filter Definition (1/2)

from–uri = sip:client1@agilent.com

request–uri = sip:client2@agilent.com

protocol = rtp

direction = tx

action = discard

Filter Definition (2/2)

from–uri = sip:client2@agilent.com

request–uri = sip:client1@agilent.com

protocol = rtp

direction = rx

action = discard

Note: In the above example:

  • Filter-1: for calls initially-established via an INVITE originating from client1, this filter discards the outbound RTP destined for client2 (from the perspective of client1) when it is received at the server.

  • Filter-2: for calls initially-established via an INVITE originating from client2, this filter discards the inbound RTP destined for client2 (from the perspective of client2) when it is received at the server.

Example 2

Delay all RTP and RTCP regardless of originating and terminating client URIs by 100ms (as in simulating complete/general end-to-end network latency for user-plane).

Filter Definition

from–uri = *

request–uri = *

protocol = *

direction = *

action = delay: 100ms

See Also

AddFilterRule (Method)

Example_API_Usage__Server


COM Wrapper

COM API (Wrapper)

Last Updated: 2014-06-02

The implementation of the E6966B application COM interface provides a thin wrapper onto the existing WCF interface. This enables an equivalent API in both the COM and WCF interfaces as it provides a one-to-one mapping between available API members.

Overview of COM Wrapper API Interworkings

The application installer performs the process of extracting COM-visible .NET-based interfaces/types and classes and registers all of the associated data into the Windows registry at installation time. Refer to Figure_1 for diagrammatic view.

The COM-based registry information is somewhat different to “native” COM references. This is because, for ProgID/class-implementation information, it references the .NET core runtime library and provides other parameters in the registry entries to identify the managed .NET DLL, versions, and so forth for which it defines and provides the exposed types.

When an unmanaged application runs and attempts to COM-initialize a COM-visible (and previously windows-registered) .NET type, it accesses via the standard GUID/PROGID identifiers which are used to consult the Windows Registry. The entries in the registry cause the .NET runtime to be invoked which dynamically generates proxy classes responsible for marshalling calls between the unmanaged application and the managed runtime. (It also causes the underlying managed class to be allocated and constructed in the managed context). As mentioned previously, the registered data in the windows registry provides the .NET core runtime with the information it requires to locate the associated managed .NET DLL for which it can then use .NET Reflection (and other capabilities) to dynamically create the proxy/stub interworking classes.

Figure 1: Overview of COM Wrapper API Interworkings

See Also

Using the COM Interface (Server)

Using the COM Interface (Client)

Using the COM Interface (Conference-Server)

COM Type/Class Identifiers (Server)

COM Type/Class Identifiers (Client)

COM Type/Class Identifiers (Conference-Server)

Example Code Using COM Interface (Server)

Example Code Using COM Interface (Client)


Using the COM Interface (Server)

Last Updated: 2014-06-02

Scripting languages generally provide dynamic/runtime resolution of Type GUIDs, however some compiled languages more commonly require static-linking/association to the GUID values (for example MS VC++). For languages which require this kind of static-linking against a binary type-library (.tlb) file, as part of the application installation the associated tlb file is provided, along with an example .NET source-code extract of the class ProgIDs and GUID definitions, to aid in utilizing the COM-wrapper interface.

The files are provided in a “COM” directory in the “API Tools” sub-directory associated with the installation and comprise the following files:

  • [E6966B_AppDir]\API Tools\COM\servercomm_comtypes.tlb

  • [E6966B_AppDir]\API Tools\COM\IDs\ServerComm_ComGuids.vb

  • [E6966B_AppDir]\API Tools\COM\IDs\ServerComm_ComProgIDs.vb

The tlb is also useful, even for developers utilizing dynamic/runtime GUID/ProgID mapping, as it is possible to use Windows-based utilities on the binary tlb file to discern API/interface details of the exported COM interfaces/members.

An example tool which can be used to inspect the tlb file is “OleView.Exe” which is provided as part of the freely available Windows SDK (and also implicitly provided as part of non-express versions of MS Visual Studio).

The design of the COM interface is such that there is a single top-level COM object which you should COM-initialize (as in via CoCreateInstance() and so forth). The top-level class implements the COM_GUID__IF_COM interface (WCF-equivalent interface: IComInterface).

Once this class has been COM-initialized, the API-accessors via this COM interface are almost identical to the .NET-managed interface definitions in terms of hierarchy.

For example, the top-level COM class (which is the only class that can be COM-instantiated directly without an error/exception being thrown in the managed runtime) provides various accessor methods which return references or pointers to implementations of sub-interfaces.

This top-level class is identified in COM by the PROGID value associated with: COM_PROGID__CLS_COM_API.

Top-Level COM Interface (as defined in VB.NET)

    ''' <summary>
    ''' Top-Level COM-accessible interface providing access to all sub-interfaces
    ''' of the application.
    ''' </summary>
    ''' <remarks></remarks>

    <ComVisible(True), Guid(ComGuids.COM_GUID__IF_ICOM)>
    <InterfaceType(ComInterfaceType.InterfaceIsDual)>
    Public Interface IComInterface
       Function Server() As     <MarshalAs(UnmanagedType.Interface)> IServer
       Function CallControl() As <MarshalAs(UnmanagedType.Interface)> ICallControl
       Function Connection() As <MarshalAs(UnmanagedType.Interface)> IConnection
       Function ClientControl() As <MarshalAs(UnmanagedType.Interface)> IClientControl
       Function Logging() As <MarshalAs(UnmanagedType.Interface)> ILogging
       Function Message() As <MarshalAs(UnmanagedType.Interface)> IMessage
       Function AlternateResponse() As <MarshalAs(UnmanagedType.Interface)> IAlternateResponse
       Function Signaling() As <MarshalAs(UnmanagedType.Interface)> ISignaling
       Function SignalingControl() As <MarshalAs(UnmanagedType.Interface)> ISignalingControl
       Function Authentication() As <MarshalAs(UnmanagedType.Interface)> IAuthentication
       Function SubscriptionManager() As <MarshalAs(UnmanagedType.Interface)>  \
                                          ISubscriptionManager

    End Interface

All of the sub-interfaces returned by the method calls in the top-level COM interface (IServer, IConnection, and so forth) are exact COM-based equivalent class re-definitions of the WCF-based equivalents.

The native .NET/WCF interfaces or classes are defined as part of the “NET” namespace within the server-communicator .NET project, whereas the COM-based classes are defined as part of the “COM” namespace in the .NET project as outlined in the table below:

Namespace | Namespace-purpose in the Server-Communicator project
NET | .NET/WCF-based types, interfaces and classes
COM | COM-based types, interfaces and classes

The server-communicator DLL is (purposefully) not dotfuscated, to enable you to have the opportunity to run a reflection tool (such as .NET Reflector) in order to get additional detailed information regarding data-types, interfaces and classes that belong to the COM namespace and have been made COM-visible.

See Also

COM Wrapper

Example Code Using COM Interface (Server)

COM Type/Class Identifiers (Server)

Example Code Using COM Interface (Client)

COM Type/Class Identifiers (Client)


COM Type/Class Identifiers (Server)

Last Updated: 2014-06-02

The identifiers outlined in this section describe a mapping between a COM-based GUID/PROGID identifier-variable (as defined in the sample code files outlined in Using the COM Interface (Server) and the equivalent WCF-based type. The associated GUID/PROG value (as registered in the Windows Registry) can be found in the “ComGuids” and “ComProgIDs” source-files provided with the application installation, and these values are used to uniquely identify COM objects/types that are registered to the Windows OS.

Mappings:

  • Enum_GUID_Mappings

  • Interface_GUID_Mappings

Enum GUID Mappings

ClientComm_ComGuid.vb variable-name | Equivalent WCF Type
COM_GUID__ENUM_MESSAGETYPE | MessageType
COM_GUID__ENUM_AKAAUTHALGORITHMTYPE | AuthAkaAlgorithmType
COM_GUID__ENUM_ALTRESPMESSAGETYPE | AltRespMessageType
COM_GUID__ENUM_AUTHCOMPARISONTYPE | AuthComparisonType
COM_GUID__ENUM_AUTHALGORITHMTYPE | AuthAlgorithmType
COM_GUID__ENUM_AUTHOPTYPE | AuthOpType
COM_GUID__ENUM_CALLSESSIONSTATE | CallSessionState
COM_GUID__ENUM_IPSEC_ENC_ALG | IPsecEncryptionAlgEnum
COM_GUID__ENUM_IPSEC_INT_ALG | IPSecIntegrityAlgEnum
COM_GUID__ENUM_SS_ACTIVESTATE | SSEnum_ActiveState
COM_GUID__ENUM_SS_IDRESTRICTMODE | SSEnum_IDRestrictionMode
COM_GUID__ENUM_SS_IDRESTRICTTYPE | SSEnum_IDRestrictionType
COM_GUID__ENUM_SS_IDRESTRICTTEMPMODE | SSEnum_IDRestrictionTempMode
COM_GUID__ENUM_MEDIATRANSFERSTATE | MediaTransferStateEnum
COM_GUID__ENUM_EMERGENCYSERVICETYPE | AgSipEmergencyServiceType
COM_GUID__ENUM_MESSAGECONTEXT | MessageContextEnum
COM_GUID__ENUM_MESSAGEPRIORITY | MessagePriorityEnum
COM_GUID__ENUM_XCAPREQUESTTYPE | XcapRequestType

Interface GUID Mappings

ClientComm_ComGuid.vb variable-name | Equivalent WCF Type
COM_GUID_IF_ICOM | ICom
COM_GUID_IF_ICONNECTION | IConnection
COM_GUID_IF_ISERVER | IServer
COM_GUID_IF_ICALLCONTROL | ICallControl
COM_GUID_IF_ICLIENTCONTROL | IClientControl
COM_GUID_IF_ISIGNALING | ISignaling
COM_GUID_IF_ISIGNALINGCONTROL | ISignalingControl
COM_GUID_IF_ILOGGING | ILogging
COM_GUID_IF_IMESSAGE | IMessage
COM_GUID_IF_IALTERNATERESPONSE | IAlternateResponse
COM_GUID_IF_IAUTHENTICATION | IAuthentication
COM_GUID_IF_ISUBSCRIPTIONMANAGER | ISubscriptionManager
COM_GUID_IF_ISUBSCRIPTION | ISubscription
COM_GUID_IF_ICONTROLPLANECONFIG | IControlPlaneConfig
COM_GUID_IF_ICONTROLPLANEFILTERMGR | IControlPlaneFilterMgr
COM_GUID_IF_IUSERPLANECONFIG | IUserPlaneConfig
COM_GUID_IF_IFILTERMGR | IFilterMgr
COM_GUID_IF_ICALLDATA | ICallData
COM_GUID_IF_IE911CONFIG | IE911Config
COM_GUID__IF_IMESSAGEACCOUNTMGR | IMessageAccountMgr
COM_GUID__IF_IMESSAGEACCOUNT | IMessageAccountData
COM_GUID__IF_ISMSCCONFIG | ISmscConfig

Class GUID and ProgID Mappings

Since the Class GUID and ProgID values are used to map to a specific implementation of a COM-visible class (and therefore correlate to an externally-visible .NET class implementation), the GUID and ProgID mappings are not outlined here. They are implemented as opposed to having defined details that can be stated.

However, it should be noted here that these ID mappings are provided in the files available to help you use the COM interface. These files are described in the "Using the COM Interface (Server)" topic and their directory locations are shown here.

See Also

COM Wrapper

Example Code Using COM Interface (Server)

COM Type/Class Identifiers (Server)

Example Code Using COM Interface (Client)

COM Type/Class Identifiers (Client)


Example Code Using COM Interface (Server)

Last Updated: 2014-06-02

This example provides the COM-based equivalent of the .NET WCF example.

The test code below performs the following:

  • Initializes various COM-visible interfaces/sub-interfaces.

  • Connects (via COM) to the WCF interface of a running server application

  • Reads the Server application version-number and displays in a Windows MessageBox

  • (After the MessageBox is closed), starts call-flow logging on the server

  • Changes the AlternateMessageResponse value to "Forbidden"

  • Reads the AddressOfRecordAll property and displays the first entry

    Note: If there are no clients registered to the server when this property is read, it will likely print a garbled string here. So, it is recommended that a client is registered to the server before running the compiled executable.

  • The sample test program then terminates.

Test Code Begins Here:

#include <stdio.h>

#include <stdlib.h>

#include <atlbase.h> // for USES_CONVERSION

// DEFINEs for the possible COM Type-Library (TLB) file info paths..

#define TLB_SRC_LOCAL 0

#define TLB_SRC_INSTALL_WIN7 1

#define TLB_SRC_INSTALL_WINXP 2

// change this and recompile when changing the path to the TLB...

#define TLB_SRC TLB_SRC_INSTALL_WIN7

#if (TLB_SRC == TLB_SRC_LOCAL)

#import "C:\TFSDevelopment\SwIFT\IMS-SIP\Server\Main\Development\ImsSipServerCommunicator\ImsSipSvrComm\bin\x86\Release\COM\servercomm_comtypes.tlb"

#elif (TLB_SRC == TLB_SRC_INSTALL_WIN7)

#import "C:\Program Files (x86)\Agilent\E6966B\API Tools\COM\servercomm_comtypes.tlb"

#else (TLB_SRC == TLB_SRC_INSTALL_WINXP)

#import "C:\Program Files\Agilent\E6966B\API Tools\COM\servercomm_comtypes.tlb"

#endif

using namespace Agilent_ImsSip_ServerComm;

IComInterface* comIF = NULL;

IServer* server = NULL;

IConnection* conn = NULL;

ILogging* logging = NULL;

IAlternateResponse *altresponse = NULL;

IClientControl *clientctrl = NULL;

ISignalingControl *signalingctrl = NULL;

ICallControl *callctrl = NULL;

// For Subscription and SubscriptionManager testing...

ISubscriptionManager *subManager = NULL;

ISubscription *subscription = NULL;

// For Filter-Mgr Testing...

IControlPlaneConfig *ctrlplaneConfig = NULL;

IUserPlaneConfig *userplaneConfig = NULL;

IControlPlaneFilterMgr *ctrlplaneFilterMgr = NULL;

IFilterMgr *ctrlplaneFilterMgrUAC = NULL;

IFilterMgr *ctrlplaneFilterMgrUAS = NULL;

IFilterMgr *userplaneFilterMgr = NULL;

/*********************************************************

* InitSubInterfaces()

*********************************************************/

void InitSubInterfaces()

{

HRESULT hr = 0;

printf ("Initing Sub Interfaces\n");

hr = comIF->raw_Connection(&conn);

if (! SUCCEEDED(hr) ) printf("failed to get conn interface!\n");

hr = comIF->raw_Server(&server);

if (! SUCCEEDED(hr) ) printf("failed to get server interface!\n");

hr = comIF->raw_Logging(&logging);

if (! SUCCEEDED(hr) ) printf("failed to get logging interface!\n");

hr = comIF->raw_AlternateResponse(&altresponse);

if (! SUCCEEDED(hr) )

printf("failed to get the alternate response interface!\n");

hr = comIF->raw_ClientControl(&clientctrl);

if (! SUCCEEDED(hr) ) printf("failed to get the client-control interface!\n");

hr = comIF->raw_SignalingControl(&signalingctrl);

if (! SUCCEEDED(hr) ) printf("failed to get the signaling-control interface!\n");

hr = comIF->raw_SubscriptionManager(&subManager);

if (! SUCCEEDED(hr) )

printf("failed to get the subscription-manager interface!\n");

hr = comIF->raw_CallControl(&callctrl);

if (! SUCCEEDED(hr) ) printf("failed to get the call-control interface!\n");

// filtering-interfaces

if (signalingctrl != NULL)

{

hr = signalingctrl->get_ControlPlaneConfig(&ctrlplaneConfig);

if (! SUCCEEDED(hr) )

printf("failed to get the control-plane-config interface!\n");

if(ctrlplaneConfig != NULL)

{

hr = ctrlplaneConfig->get_ControlPlaneFilterMgr(&ctrlplaneFilterMgr);

if (! SUCCEEDED(hr) )

printf("failed to get the (top) control-plane filter-mgr interface!\n");

if (ctrlplaneFilterMgr != NULL)

{

hr = ctrlplaneFilterMgr->get_FilterMgr_UAC(&ctrlplaneFilterMgrUAC);

if (! SUCCEEDED(hr) )

printf("failed to get the control-plane UAC filter-mgr!\n");

hr = ctrlplaneFilterMgr->get_FilterMgr_UAS(&ctrlplaneFilterMgrUAS);

if (! SUCCEEDED(hr) )

printf("failed to get the control-plane UAS filter-mgr!\n");

}

}

hr = signalingctrl->get_UserPlaneConfig(&userplaneConfig);

if (! SUCCEEDED(hr) ) printf("failed to get the user-plane-config interface!\n");

if (userplaneConfig != NULL)

{

hr = userplaneConfig->get_FilterMgr_UP(&userplaneFilterMgr);

if (! SUCCEEDED(hr) ) printf("failed to get the user-plane filter-mgr!\n");

}

}

printf ("Initing Sub Interfaces Complete!\n");

}

/*********************************************************

* GetErrorInfo()

*********************************************************/

void GetErrorInfo(bool showMsgBox)

{

HRESULT hr = 0;

USES_CONVERSION;

CComBSTR mystring;

hr = conn->get_ErrorInformation(&mystring);

if (SUCCEEDED(hr))

{

LPCSTR convertedStr = OLE2CT(mystring);

printf ("succeeded in getting ErrorInformation! (%s)\n", convertedStr);

if (showMsgBox)

MessageBox (NULL, convertedStr, TEXT("Message is..."), MB_OK);

}

else

printf ("failed to get ErrorInformation!\n");

}

/*********************************************************

* Test Subroutine definition section

*

* NOTE: The IConnection test routine should always be

* called before any others as this one connects

* via WCF to the server application...!

*********************************************************/

VARIANT_BOOL IConnection_Test(char *pIpAddressStr, int portNumber)

{

VARIANT_BOOL success = false;

HRESULT hr = 0;

CComBSTR comBStr;

if (conn != NULL)

{

GetErrorInfo(false);

printf("got a conn ptr!\n");

comBStr = pIpAddressStr;

hr = conn->raw_Initialize(comBStr, portNumber, &success);

if (SUCCEEDED(hr))

printf("succeeded in performing initialize!\n");

else

printf("failed to perform initialize()!\n");

GetErrorInfo(false);

}

return success;

}

VARIANT_BOOL IServer_Test()

{

USES_CONVERSION; // Provides OLE2CT definition etc..

VARIANT_BOOL success = false;

HRESULT hr = 0;

CComBSTR comBStr;

// IServer control

if (server != NULL)

{

printf("got a server ptr!\n");

hr = server->get_Version(&comBStr);

if (SUCCEEDED(hr))

{

printf("successfully read server version!\n");

MessageBox (NULL, OLE2CT(comBStr), TEXT("Message is..."), MB_OK);

}

else

printf("failed to read server version! (0x%08x)\n", hr);

success = SUCCEEDED(hr);

}

return success;

}

VARIANT_BOOL ILogging_Test()

{

VARIANT_BOOL success = false;

HRESULT hr = 0;

// ILogging control

if (logging != NULL)

{

printf("got a logging ptr!\n");

hr = logging->raw_StartCallFlow();

if (SUCCEEDED(hr))

printf("successfully started call-flow logging!\n");

else

printf("failed to start call-flow logging!\n");

success = SUCCEEDED(hr);

}

return success;

}

VARIANT_BOOL IAlternateResponse_Test()

{

VARIANT_BOOL success = false;

HRESULT hr = 0;

// IAlternateResponse control

if (altresponse != NULL)

{

enum AltRespMessageType blah;

printf("got an altresponse ptr!\n");

hr = altresponse->get_MessageResponse(&blah);

if (SUCCEEDED(hr))

{

printf("succeeded reading message-response. value = %d\n", blah);

blah = AltRespMessageType_Forbidden;

hr = altresponse->put_MessageResponse(blah);

if (SUCCEEDED(hr))

printf("succeeded modifying message-response!\n");

else

printf("failed to modify message-response!\n");

}

else

printf("failed to read message-response value!\n");

success = SUCCEEDED(hr);

}

return success;

}

VARIANT_BOOL IClientControl_Test()

{

USES_CONVERSION; // Provides OLE2CT definition etc..

VARIANT_BOOL success = false;

HRESULT hr = 0;

// IClientControl control

if (clientctrl != NULL)

{

SAFEARRAY *aorArray;

printf("got a client-control pts!\n");

hr = clientctrl->get_AddressOfRecordAll(&aorArray);

if (SUCCEEDED(hr))

{

int z;

long indices[1];

void *pv;

printf("succeeded reading AddressOfRecordAll Property: \n");

for(z=0; z< 1; z++)

{

indices[0] = z;

SafeArrayGetElement(aorArray,

indices,

&pv);

printf("%s", OLE2CT((LPCWSTR)pv));

}

printf("\n");

hr = SafeArrayDestroy(aorArray);

if (!SUCCEEDED(hr))

printf("failed to destroy safe-array!\n");

//MessageBox (NULL, OLE2CT((LPCWSTR)aorArray->pvData),

// TEXT("Message is..."), //MB_OK);

}

else

printf("failed to get AddressOfRecordAll property!\n");

success = SUCCEEDED(hr);

}

return success;

}

VARIANT_BOOL ISubscriptionManager_Test(bool useMessageBoxes)

{

// The procedure for this test routine is as follows...

// 1 - Add a new subscription for "sip:COM_testuser1@test.com"

// 2 - Duplicate this subscription to "sip:COM_duplicatedtestuser1@test.com"

// 3 - Remove the original subscription created in (1)

// 4 - Modify the duplicated subscription (from step (2))

// 5 - Remove the newly modified subscription..

//

// Intermediate message-boxes are optionally used to halt the application at

// each stage to allow the tester to manually confirm the changes in the

// server application...

USES_CONVERSION; // Provides OLE2CT definition etc..

VARIANT_BOOL success = false;

HRESULT hr = 0;

CComBSTR comBStr1;

CComBSTR comBStr2;

CComBSTR comBStr3;

char newAssertedIdStr[] = "sip:COM_testuser1@test.com";

char dupAssertedIdStr[] = "sip:COM_duplicatedtestuser1@test.com";

char modAssertedIdStr[] = "sip:COM_modifiedtestuser1@test.com";

ISubscription *pSubscription;

struct SupplementaryServiceStruct ssConfig;

SAFEARRAY *pAssociatedUserIdArray = NULL;

// ISubscriptionManager control

if (subManager != NULL)

{

printf("\n\nSUBSCRIPTION_MGR TEST....\n");

// 1 - Add a new subscription..

comBStr1 = newAssertedIdStr;

hr = subManager->raw_AddNewSubscription(comBStr1, &pSubscription);

if (SUCCEEDED(hr))

{

printf("successfully added new subscription!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was added okay...

MessageBox (NULL, "Please verify new subscription has been added!",

TEXT("Message is..."), MB_OK);

}

// 2 - Duplicate the subscription

comBStr2 = dupAssertedIdStr;

hr = subManager->raw_DuplicateExistingSubscription(comBStr1,

comBStr2,

&pSubscription);

if (SUCCEEDED(hr))

{

printf("successfully duplicated the subscription!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was

// duplicated okay...

MessageBox (NULL, "Please verify new subscription has been duplicated!",

TEXT("Message is..."), MB_OK);

}

// 3 - Remove the originally created subscription

hr = subManager->raw_RemoveSubscription(comBStr1, &success);

if (SUCCEEDED(hr))

{

printf("successfully removed original subscription!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was

// removed okay...

MessageBox (NULL,

"Please verify original subscription has been removed!",

TEXT("Message is..."), MB_OK);

}

// 4 - Modify the duplicated subscription

hr = subManager->raw_GetSubscriptionData(comBStr2, &pSubscription);

if (!pSubscription)

{

printf("Failed to retrieve subscription data for duplicated user!\n");

return false;

}

comBStr3 = modAssertedIdStr;

// configure the supplementary-service data that we wish to associate with

// our changed subscription-data (and commit back into the subscriber

// database)

ssConfig.OipConfig.Active = 0;

ssConfig.OirConfig.Active = 1;

ssConfig.OirConfig.Mode = SSEnum_IDRestrictionMode_Permanent;

ssConfig.OirConfig.TemporaryMode =

SSEnum_IDRestrictionTempMode_PresRestricted;

ssConfig.OirConfig.RestrictionType =

SSEnum_IDRestrictionType_RestrictAllPrivateHeaderInfo;

ssConfig.TipConfig.Active = 0;

ssConfig.TirConfig.Active = 1;

ssConfig.TirConfig.Mode = SSEnum_IDRestrictionMode_Permanent;

ssConfig.TirConfig.TemporaryMode =

SSEnum_IDRestrictionTempMode_PresRestricted;

// hacky compound-statement (curly-braced) for allocating and

// populating the SafeArray for the associatedUserIdList....

{

char *associatedIdStrs[] = { "deeble", "feeble", "keeble", "weeble",

"neeble", "jeeble", "reeble", "peeble",

"zeeble", "mcNeeble" };

int nDims = 1;

int nElems = 10;

long indices[1];

void *pv;

indices[0] = nElems;

pAssociatedUserIdArray = SafeArrayCreateVector(VT_BSTR, 0, nElems);

for (int i=0; i<nElems; i++)

{

indices[0] = i;

SafeArrayPutElement (pAssociatedUserIdArray, indices,

A2BSTR(associatedIdStrs[i]));

}

}

// copy the various modified properties into our ISubscription

// object so that the changed-object is ready to be applied back

// into the subscriber database...

hr = pSubscription->put_AssertedId(comBStr3);

hr = pSubscription->put_AssociatedUserIdList( pAssociatedUserIdArray );

hr = pSubscription->put_SuppServiceConfig(ssConfig);

// apply/commit the changed subscription object back into

// the subscriber-database

hr = subManager->raw_ApplySubscriptionChanges(comBStr2, pSubscription,

&success);

SafeArrayDestroy(pAssociatedUserIdArray);

if (SUCCEEDED(hr) && success)

{

printf("successfully modified the subscription!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user

// was removed okay...

MessageBox (NULL, "Please verify duped subscription has been modded!",

TEXT("Message is..."), MB_OK);

}

// 5 - Remove the newly modified subscription...

hr = subManager->raw_RemoveSubscription(comBStr3, &success);

if (SUCCEEDED(hr) && success)

{

printf("successfully removed the modified subscription!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the

// user was removed okay...

MessageBox (NULL, "Please verify modified subscription has " \

"been removed!",

TEXT("Message is..."), MB_OK);

}

}

else

printf("failed to remove the modified subscription!\n");

}

else

printf("failed to modify subscription!\n");

}

else

printf("failed to remove original subscription!\n");

}

else

printf("failed to duplicate subscription!\n");

}

else

printf("failed to add new subscription!\n");

success = SUCCEEDED(hr);

}

return success;

}

VARIANT_BOOL ICallControl_Test(bool useMessageBoxes)

{

// The procedure for this test routine is as follows...

// 1 - Query and obtain a snapshot of the current user-plane media-core statistics

// (and other call-session data)

// 2 - Reset all user-plane/call-session data statistics.

//

// Intermediate message-boxes are optionally used to halt the application at

// each stage to allow the tester to manually confirm the changes in the

// server application...

USES_CONVERSION; // Provides OLE2CT definition etc..

VARIANT_BOOL success = false;

HRESULT hr = 0;

CComBSTR comBStr1;

CComBSTR comBStr2;

CComBSTR comBStr3;

SAFEARRAY *pSessionDataSnapshotArray = NULL;

// Filtering-core testing

printf("\nCALL_CONTROL TEST....\n");

if (callctrl != NULL)

{

if(useMessageBoxes)

{

// Display message-box prompting user to verify the user was removed okay...

MessageBox (NULL, "Please ensure that the user-plane media proxy capability is"\

" enabled in the Server and an IMS call is established"\

" between two clients!",

TEXT("Message is..."), MB_OK);

}

// 1 - Query/obtain session-data snapshot

hr = callctrl->raw_GetSessionDataSnapshot(&pSessionDataSnapshotArray);

if(SUCCEEDED(hr))

{

int i;

long numElems;

longindices[1];

ICallData *pCallData;

printf("successfully retrieved the session-stats snapshot.\n");

// get the number of elements (i.e. ICallData elements)

hr = SafeArrayGetUBound(pSessionDataSnapshotArray, 0, &numElems);

printf("numSessionsInSnapshotData = %d\n\n", numElems);

// loop through each element printing some info from each entry

for (i=0; i<numElems; i++)

{

indices[0] = i;

hr = SafeArrayGetElement(pSessionDataSnapshotArray, indices,

(void *) &pCallData);

if ( SUCCEEDED(hr))

{

hr = pCallData->get_OriginatingUri(&comBStr1);

hr = pCallData->get_TerminatingUri(&comBStr2);

hr = pCallData->get_CallID(&comBStr3);

printf("session-data:\n\t[orig-uri: %s],\n\t[term-uri: %s],\n\t[call-id: %s]\n",

OLE2CT((LPCWSTR)comBStr1),

OLE2CT((LPCWSTR)comBStr2),

OLE2CT((LPCWSTR)comBStr3));

}

else

printf("failed to get element-data from session-data snapshot!\n");

}

// release the resources allocated to the session-data snapshot SafeArray.

SafeArrayDestroy(pSessionDataSnapshotArray);

}

else

printf("failed to retrieve a call-control session-data snapshot!\n");

// 2 - Reset all user-plane/call-session data statistics.

hr = callctrl->raw_ResetAllSessionDataStatistics();

if(SUCCEEDED(hr))

{

printf("successfully reset/cleared the session-data stats.\n");

if(useMessageBoxes)

{

// Display message-box prompting user to verify the user was removed okay...

MessageBox (NULL, "Please verify that the UP session-stats have been reset!",

TEXT("Message is..."), MB_OK);

}

}

else

printf("failed to reset/clear session-data statistics!\n");

}

else

printf("No Call-Control interface is available for performing testing.\n");

return success;

}

VARIANT_BOOL FilteringCore_Test(bool useMessageBoxes)

{

// The procedure for this test routine is as follows...

// 1 - Add a control-plane UAC filter rule:

// "from: FROMUAC, request-uri: REQUAC, request=REGISTER, action=discard"

// 2 - Add a control-plane UAS filter rule:

// "from: FROMUAS, request-uri: REQUAS, responses=200 OK, action=delay:50ms"

// 3 - Add a user-plane filter-rule:

// "from: FROMUP, request-uri: REQUP, prot=rtcp, direction=rx, action=none"

// 4 - Get Trigger-Count for user-plane rule

// 5 - Remove all rules in steps 1-3

//

// Intermediate message-boxes are optionally used to halt the application at

// each stage to allow the tester to manually confirm the changes in the

// server application...

USES_CONVERSION; // Provides OLE2CT definition etc..

VARIANT_BOOL success = false;

HRESULT hr = 0;

long ruleId;

longtriggerCount;

CComBSTR comBStr1;

CComBSTR comBStr2;

CComBSTR comBStr3;

#define CRLF "\r\n"

char ctrlplaneUACRuleStr[] = "from-uri = FROMUAC" CRLF "request-uri = REQUAC" CRLF \

"request = REGISTER" CRLF CRLF "action = discard" CRLF;

char ctrlplaneUASRuleStr[] = "from-uri = FROMUAS" CRLF "request-uri = REQUAS" CRLF \

"response = 200 OK" CRLF CRLF "action = delay:50ms" CRLF;

char userplaneRuleStr[] = "from-uri = FROMUP" CRLF "request-uri = REQUP" CRLF \

"protocol = rtcp" CRLF "direction = rx" CRLF CRLF \

"action = none" CRLF;

// Filtering-core testing

printf("\nFILTERING_CORE TEST....\n");

// 1 - Add a control-plane UAC filter rule

if (ctrlplaneFilterMgrUAC != NULL)

{

comBStr1 = ctrlplaneUACRuleStr;

hr = ctrlplaneFilterMgrUAC->raw_AddFilterRule(comBStr1, &ruleId);

if (SUCCEEDED(hr))

{

printf("successfully added control-plane UAC filter rule!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was added okay...

MessageBox (NULL, "Please verify new CP UAC filter rule has been added!",

TEXT("Message is..."), MB_OK);

}

}

else

printf("failed to add control-plane UAC filter rule!\n");

}

else

printf ("No control-plane UAC filter interface available!");

// 2 - Add a control-plane UAS filter rule

if (ctrlplaneFilterMgrUAS != NULL)

{

comBStr2 = ctrlplaneUASRuleStr;

hr = ctrlplaneFilterMgrUAS->raw_AddFilterRule(comBStr2, &ruleId);

if (SUCCEEDED(hr))

{

printf("successfully added control-plane UAS filter rule!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was added okay...

MessageBox (NULL, "Please verify new CP UAS filter rule has been added!",

TEXT("Message is..."), MB_OK);

}

}

else

printf("failed to add control-plane UAS filter rule!\n");

}

else

printf ("No control-plane UAS filter interface available!");

// 3 - Add a user-plane filter rule

if (userplaneFilterMgr != NULL)

{

comBStr3 = userplaneRuleStr;

hr = userplaneFilterMgr->raw_AddFilterRule(comBStr3, &ruleId);

if (SUCCEEDED(hr))

{

printf("successfully added user-plane filter rule!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was added okay...

MessageBox (NULL, "Please verify new UP filter rule has been added!",

TEXT("Message is..."), MB_OK);

}

// 4 - Get Trigger-Count for user-plane rule

hr = userplaneFilterMgr->raw_GetTriggerCounterById(ruleId, &triggerCount);

if (SUCCEEDED(hr))

{

printf("successfully read user-plane trigger-count (%d)" \

"for filter-rule (ID: %d)\n", triggerCount, ruleId);

}

else

printf("failed to retrieve trigger-count for filter-rule (ID: %d)\n",

ruleId);

}

else

printf("failed to add user-plane filter rule!\n");

}

else

printf ("No user-plane filter interface available!");

// 5 - Remove all rules in steps 1-3

if(ctrlplaneFilterMgrUAC != NULL)

{

hr = ctrlplaneFilterMgrUAC->raw_RemoveAllFilterRules();

if (SUCCEEDED(hr))

printf("successfully removed all control-plane UAC filter-rules.\n");

else

printf("failed to remove control-plane UAC filter-rules.\n");

}

if(ctrlplaneFilterMgrUAS != NULL)

{

hr = ctrlplaneFilterMgrUAS->raw_RemoveAllFilterRules();

if (SUCCEEDED(hr))

printf("successfully removed all control-plane UAS filter-rules.\n");

else

printf("failed to remove control-plane UAS filter-rules.\n");

}

if(userplaneFilterMgr != NULL)

{

hr = userplaneFilterMgr->raw_RemoveAllFilterRules();

if (SUCCEEDED(hr))

printf("successfully removed all user-plane filter-rules.\n");

else

printf("failed to remove user-plane filter-rules.\n");

}

if(useMessageBoxes)

{

// Display message-box prompting user to verify the user was added okay...

MessageBox (NULL, "Please verify that the control-plane UAC, UAS and " \

"also user-plane rules have been removed!",

TEXT("Message is..."), MB_OK);

}

// I know that this only considers (and returns) the status of the

// last performed COM operation.. but this is only a sample..

// there's enough printf's and message-boxes to help navigate even the most

// weary of travellers..

success = SUCCEEDED(hr);

returnsuccess;

}

/*********************************************************

* Main Routine

*********************************************************/

int main(int argc, char *argv[])

{

char *ip_address_string_ptr;

char *port_num_string_ptr;

int portNumber;

HRESULT hr = 0;

VARIANT_BOOL success = false;

CLSID cls;

// Process the command-line params

if (argc != 3)

{

printf("\n\tUsage - comtest.exe <ip_address_string> <port_number>\n");

return 1;

}

ip_address_string_ptr = argv[1];

port_num_string_ptr = argv[2];

portNumber = atoi(port_num_string_ptr);

// do the COM testing...

hr = CLSIDFromProgID (L"Agilent.E6966B.ImsSipServer.ComAPI", &cls);

hr = CoInitialize(NULL);

if (! SUCCEEDED(hr))

{

printf("failed to CoInitialize()!\n");

return 0;

}

if (SUCCEEDED(hr))

{

hr = CoCreateInstance (cls, NULL, CLSCTX_INPROC_SERVER,

__uuidof(IComInterface), (void **) &comIF);

if (SUCCEEDED(hr))

{

CComBSTR mystring;

// Sub-interfaces *MUST* be initialized prior to calling

// any interface test-functions

InitSubInterfaces();

// IConnection testing (and initial WCF-based connectivity!)

success = IConnection_Test(ip_address_string_ptr, portNumber);

// IServer testing

success = IServer_Test();

// ILogging testing

success = ILogging_Test();

// IAlternateResponse testing

success = IAlternateResponse_Test();

// IClientControl testing

success = IClientControl_Test();

// ISubscriptionManager testing

ISubscriptionManager_Test(true);

// ICallControl testing

ICallControl_Test(true);

// Filtering-Core testing (control-plane UAC, UAS and

// user-plane filter-managers)..

FilteringCore_Test(true);

comIF->Release();

}

else

printf("Failed to create IComInterface! (0x%08x)\n", hr);

}

else

printf("Failed to find CLSID!\n");

CoUninitialize();

if (! SUCCEEDED(hr))

{

printf("failed to CoUninitialize()!\n");

return 0;

}

else

printf ("succeeding in performing CoUninitialize()!\n");

return 0;

}

See Also

COM Wrapper

Using the COM Interface (Server)

COM Type/Class Identifiers (Server)

Using the COM Interface (Client)

Example Code Using COM Interface (Client)

COM Type/Class Identifiers (Client)


Client User Interface

Client User Interface (UI)

Last Updated: 2014-06-02

The IMS-SIP Client Emulator Software is a software application designed to run in conjunction with an IMS-SIP Server for the purposes of testing and demonstrating a UE's ability to perform VoIP, Video, and SMS/MMS over an IP infrastructure using IMS architecture. To support End-to-End (E2E) application testing, two clients and one server are required.

For more information on using the IMS-SIP Client, refer to the following topics:

  • Overview

  • VoIP

  • Send SMS

  • Audio Video

  • Configuration


Overview-Client UI

Overview: Client User Interface (UI)

Last Updated: 2012-03-02

The IMS-SIP Client Emulator Software User interface (UI) can be divided into seven areas shown in the figure below. They are:

    • Register Unregister

    • User name

    • Line Select Control

    • Activity and Configuration Tabs

    • Activity and Configuration Setup

    • Information and Output Display

    • Information and Output Tabs

    • Status Strip

1 Register/Unregister

Provides the client with the ability to initiate SIP Registration and De-registration.

2 User name

Displays the configured SIP user name associated with the client, to facilitate easy identification when performing end-to-end testing.

3 Line Select Control

Provides the ability to quickly switch between lines when performing multiple simultaneous VoIP calls.

4 Activity and Configuration Tabs

Enables you to select an activity or configure your setup. For details on a specific tab, refer to these topics:

  • VoIP

  • Send SMS

  • Audio Video

  • Configuration

5 Activity and Configuration Setup

Displays and provides access to the various settings associated with the currently selected activity or configuration tab.

6 Information and Output Display

Displays the information associated with the currently selected Information or Output tab.

7 Information and Output Tabs

Enables you to select the type of information or output you would like to display in area 6, above. This information is useful in debugging your tests.

8 Status Strip

Provides useful information regarding the current status of the client, including: Registration-state, WCF API Port, and line-status for all VoIP lines.


VoIP

Last Updated: 2014-06-02

The VoIP tab on the IMS-SIP Client user interface enables you to configure and control a voice call over an IP network. Refer to the following sections for descriptions of their use.

  • Call Location

  • Call Control

  • Line Selection

  • Codec Config

  • Miscellaneous Configuration

A call can only be connected if a microphone is configured and available.

Call Location

  • The address (name@domain) that is registered with the SIP server that is to be called.

The "@domain" portion of the address can be omitted enabling calls to be made with the name portion only, for example when using a phone number. The @domain portion is added by the IMS server based on the information entered in the server realm/domain field.

This field shows the line-specific call-location value configured for the currently selected/active line. If the selected call-line is changed, this field is updated to the value associated with the newly selected line.

Call Control

  • Number pad input: Use these numbers to send Dual-Tone Multi-Frequency (DTMF) tones as RTP to the VoIP peer client.

  • Dial: Initiates a VoIP call to the user specified in the Call Location field. This option is only enabled if the phone is registered with a SIP Server and is only visible when the currently selected line state is idle.

  • Answer: Accepts an incoming call. This option is only visible when the currently selected line has an incoming call.

  • Reject: Rejects an incoming call (and disallows the VoIP connection establishment). This option is only visible when the currently selected line has an incoming call.

  • Hang Up: Ends an on-going VoIP connection. This option is only visible when the currently selected line state is not-idle.

  • Hold: Puts an ongoing call into a local-hold state. This option is only enabled when the currently selected line state is active.

  • Resume: Resumes or un-holds an ongoing call from the previous local-hold state. This option is only enabled and visible when the currently selected line state is local-hold.

  • Update: Performs a call-session update using the SIP re-INVITE request method on the current line (and apply any newly configured codec-settings to an active call). This option is only enabled when the currently selected line state is active.

  • Transfer: Transfers a call on a VoIP session established on the current line. The target URI for the call-transfer is specified by the related Call-Transfer_Target GUI setting. This option is only enabled and visible when the currently selected line state is active.

  • Conference: Performs call-conferencing on the active and current line.

  • Call-conferencing performs the following:

  • Caches the peer/endpoint URI of the endpoint associated with the call on the active line.

  • Auto-switchs the local call-line to the line on which a call to a conference-server is established.

  • Send a “REFER” to the conference-server specifying the cached peer/endpoint URI as the “Refer-To” target.

  • This option is only enabled and visible when:

  • the currently selected line state is active, and

  • the current line has not already been placed in a conference call and

  • the client initiating the transfer has an established call to a conference-server on another call line.

Line Selection

  • Line selector: Selects the current line. Changing the current line places the previously selected line on local-hold if it is currently in the active state. Any line-specific settings (for example: Call Location) are updated to reflect the value associated with the new line selection.

  • Line status group: Indicates the current state of each of the supported VoIP lines.

Codec Config

  • Audio: Enables modification of the currently active audio codec set.

  • Video: Enables modification of the currently active video codec set.

Line Status

  • Call Endpoint URI: Displays the URI of the peer client that is currently connected on the call/session (associated with the currently selected line).

  • Type: Displays the high-level type of the call (associated with the currently selected line). The type is currently categorized as either “peer-to-peer” or “conference”.

  • State: Displays the current state of the call/session (associated with the currently selected line).

  • Audio: Indicates whether the established call (associated with the currently selected line) has negotiated the use of an audio media-stream.

  • Video: Indicates whether the established call (associated with the currently selected line) has negotiated the use of a video media-stream.

  • Audio Codecs: Displays a summary list of the successfully negotiated audio-codecs (for the session associated with the currently selected line).

Call-Transfer Target

  • The target URI for call-transfer.

Miscellaneous Configuration

  • Auto Answer:Configures whether the client is configured to automatically answer (accept) an incoming VoIP call.

  • Mute microphone:Mutes or Un-mutes the microphone during a VoIP call. This control is only accessible during a VoIP call.

  • Enable received audio loopback: If selected, the received audio is looped back by this client to the peer VoIP client. The control is only accessible during a VoIP call.


Send SMS

Last Updated: 2014-06-02

The Send SMS tab on the IMS-SIP Client user interface enables you to configure and send an SMS message to another client who is already registered with the server. Refer to the following sections for descriptions of their use.

  1. Send_to

  2. Mime_type_Mime_subtype

  3. Message_to_send

1 Send to

Specify the registered user to whom you wish to send a message.

Note: If the domain is already specified in the Realm-Domain field of the server emulator software, you need only enter the user name.

Repeat send: If this option is enabled, a sent message is re-sent a specified number of times with a specified delay between each repetition.

  • Repeat times:Specifies the number of times the message is re-sent. This control is only accessible if Repeat Send is enabled.

  • Delay between sends (ms):Specifies the delay (in ms) between each repeated transmission of a sent message. This control is only accessible if Repeat Send is enabled.

  • Send Default 3gpp.sms: Sends a predefined text message encoded into a 3GPP SMS message. The predefined message content is contained in the ImsSipClientSettings.xml file, which is located here:

  • For Windows XP: C:\Documents and Settings\All Users\Documents\Agilent\E6966B\IMS-SIP Client\ImsSipClientSettings.xml

  • For Windows 7: C:\Users\Public\Documents\Agilent\E6966B\IMS-SIP Client\ImsSipClientSettings.xml

  • Send Default 3gpp2.sms: Sends a predefined (and pre-encoded) binary 3GPP2 SMS message. If this option is selected, the other settings for controlling messaging have no effect. This button sends the message correctly. The hex information for this message is contained in the ImsSipClientSettings.xml file, which is located here:

  • For Windows XP: C:\Documents and Settings\All Users\Documents\Agilent\E6966B\IMS-SIP Client\ImsSipClientSettings.xml

  • For Windows 7: C:\Users\Public\Documents\Agilent\E6966B\IMS-SIP Client\ImsSipClientSettings.xml

Default 3gpp2 messages send a fixed hex sequence without updating the message sequence number. UEs receive the message when first sent and then do not display subsequent message re-sending until their SMS receive buffer has been cleared by a power off-on cycle.

2 Mime type/Mime subtype

  • text/plain: Sends the message in ASCII format.

  • application/vnd.3gpp.sms: Sends the message in this format. If hex information is to be sent then it must be formatted (and pre-encoded) appropriately for application/vnd.3gpp.sms and the proper type/subtype must be selected.

  • application/vnd.3gpp2.sms: Sends the message in this format. If hex information is to be sent then it must be formatted (and pre-encoded) appropriately for application/vnd.3gpp2.sms and the proper type/subtype must be selected.

  • User defined: Specifies the usage of a user-defined Content-Type within SIP MESSAGEs which are sent.

  • Type: This field is only available if User Defined is selected.

  • Subtype: Enables specification of the MIME sub-type.

The Mime type/Mime subtype field(s) only influence the MIME content type which is indicated in the "Content-Type" header of SIP MESSAGE signaling primitives, and does not influence the content in the message body section of the SIP MESSAGE in any way..

3 Message to send

Send as hex data: Select this if the Message box, described below contains hex information. This hex information must be formatted and encoded correctly for the given Mime Type/Mime subtype.

  • If you wish to send the message in hex format, ensure it is formatted and encoded correctly for either application/vnd.3gpp.sms or application/vnd.3gpp2.sms and that the proper type type/subtype is selected.

Message box: If this is the client that is sending the message, type the message you wish to send here. To send the message in hex format, select the box labeled, "Send as hex data".

Send Message: Sends the message in the Message to send text box with the conditions defined by the Mime type/Mime subtype settings.


Audio Video

Last Updated: 2014-06-02

The Audio Video tab on the IMS-SIP Client user interface enables you to control the Audio and Video test options. Descriptions for Audio_Controls and Video_Controls are available below.

Audio Controls

Audio control

Start Record: Starts recording the audio received. The received audio is stored in the file specified by the Record File Location and Record File name settings in: Configuration > File Location > Audio Files > Record.
Note: Each time a recording is made, a timestamp is auto-appended to the recording file-name.

Stop Record: Stops a previously started audio recording activity. (This selection is only visible when you are recording.)

Send Test: Sends the audio that is stored in the file specified by the following setting:Configuration > File Locations > Test file name location.

It is recommended that audio test files use 8 or 16 kHz sample rates.

Audio playback settings

Repeat: Enables you to control whether file-playback automatically repeats when the end-of-file is reached during audio-file transmission using the Send Test functionality. If repeat is disabled, the audio input automatically reverts to the configured microphone/input device when the end-of-file is reached.

Audio record settings

Captured Content: Specifies the audio-stream direction(s) captured to the record-file during audio-recording. This option can only be changed while the SIP client is not actively performing an audio-recording operation.

Video Controls

Video Control

Start Record: Starts recording the video received. The received video is stored in the file specified by the Record File Location and Record File Name settings in: Configuration > File Location > Video files > Record.
Note: Each time a recording is made, a timestamp is auto-appended to the recording file-name.

Stop Record: Stops a previously started video recording activity. (This selection is only visible when you are recording.)

Send Test: Sends the video file stored at the location specified by the setting:

Configuration > File Locations > Video files > <Test file name location>. The AVI file format must contain a video encoded with one of the following codecs: H.263, H.263+, H.264.

View Local: Shows the video that the local camera is capturing

Send Local: Sends the video (to the remote peer) that the local camera is capturing while on a VoIP call.

Video playback settings

Repeat: Enables you to control whether file-playback automatically repeats when the end-of-file is reached during video-file transmission using the Send Test functionality. If repeat is disabled, the video input automatically reverts to the configured camera/input device when the end-of-file is reached.

Include audio: Enables you to control whether audio contained in the media file is provided to the specified audio-output device or not. Audio data contained within the media file must be in a compatible coding.

Video record settings

Captured Content: Specifies the video-stream direction(s) captured to the record-file during video-recording. This option can only be changed while the SIP client is not actively performing an video-recording operation. Note that once a recording has been started, the file creation (and data capturing) does not begin until the first video frame is received. (This means that the start of actual data-recording is triggered off the receiving of a decoded video frame.)

Recording Codec: Specifies the video-codec used during video-recording.

Notes:

  1. Video requires that you configure a camera (or virtual device) in the system, selected by setting:
    Configuration > Video > Camera.
  2. A call can only be connected if a microphone (or virtual device) is configured and available.


Configuration

Last Updated: 2014-06-02

The Configuration tab enables you to configure resources used by the client.

The settings and controls associated with this tab are split into the following categories:

    • Audio

    • Connection

    • File_Locations

    • General

    • QoS

    • Video

Audio

Audio streaming settings

Speaker: Enables selection of the speaker (output audio device)

Use Virtual Device: Enables you to specify whether to use a virtual audio device. When this option is enabled, the “Speaker selection” and “Microphone selection” settings are inaccessible. If no physical speaker and/or microphone device is detected or available when the application is first loaded, this setting is implicitly enabled and unchangeable. Otherwise, this setting can only be accessed or modified when the client application is not currently registered to an IMS-SIP Server.

Microphone: Enables selection of the microphone (input audio device).

Volume

Speaker: Enables you to set the volume levels for the currently selected Speaker device.

Microphone: Enables you to set the volume levels for the currently selected Microphone device.

Reset Levels (Volume): Reverts the volume levels for the currently selected Speaker and Microphone devices to an internal default value.
Note: This control is only accessible if the Client application is currently registered to an IMS-SIP Server.

Start Loop Test: Performs a loopback of the microphone (output) to the speaker (input) locally to test the volume settings.
Note: This control is only accessible if the Client application is currently registered to an IMS-SIP Server and is not in play-local mode.

Stop Loop Test: Stops a previously enabled local audio-loopback mode. Note: This button is only visible on the GUI when local audio-loopback mode is currently active.

Play Local: Enables you to play an audio file out of the local Speaker/audio-output device. The file played is specified by the Test_file_name_location setting. Note: This control is only accessible if the Client application is currently registered to an IMS-SIP Server and is not in local audio-loopback mode.

Stop Local: Stops the application running in play-local state. Note: This button is only visible and accessible when play-local mode/state is currently active.

Dynamic Audio Levels

Provides a visual display of the instantaneous input/output levels of the audio Speaker and Microphone hardware/devices.

Audio Codec Config

Provides access to codec-specific audio parameters.

General — Audio codec configuration: Provides access to some general settings regarding the audio code configuration.

Available codecs: Enables selection of the available codec set used for VoIP calls (for example: those indicated in the SDP offer). Supported codecs are:

      • AMR (8 kHz/narrowband)

      • AMR-wb (16 kHz/wideband)

      • G711 aLaw

      • G711 uLaw

      • G722

      • G722.1

      • G729

      • GSM 6.10

      • iLBC

      • speex

      • speex-wb

Codec Prioritization: Enables arrange by priority the selected codec set used for VoIP calls. Select the codec you want to move and use the arrows to set the priority location in the list.

Audio Enhancements: Enables configuration of the required audio effects/enhancements to apply during VoIP calls. The available effects are:

      • Acoustic Noise Cancellation (AEC),

      • Automatic Gain Control (AGC),

      • Voice Activity Detection (VAD)

Audio Attributes: Enables of attributes to apply during VoIP calls. The available attributes are:

      • ptime: Provides control over the preferred packetization interval in SDP offers/answers. You can select or clear the check box to include or exclude the ptime attribute. When ptime inclusion is enabled, the value must be in the range [20ms-60ms], and the increment value is 20ms.

      • maxptime: Provides control over the maximum acceptable packetization interval in SDP offers or answers. You can select or clear the check box to include/exclude the maxptime attribute. When maxptime inclusion is enabled, the value must be in the range [20ms-60ms], and the increment value is 20ms.

AMR — AMR Configuration: Provides access to AMR Configuration settings.

RTP Payload Type: Enables you to set a payload-type value. This value is used to identify a particular (IANA registered) encoding/payload format (along with any additional parameters such as clock-rate, number of channels, etc.). The value range is from 96 to 127.

Octet Alignment: Provides the ability to configure the octet-alignment mode which is signalled (to the peer) and used for client-initiated sessions/calls utilizing the AMR codec. AMR octet-alignment is outlined further in RFC 4867.

Include Mode Set and Mode Set: Enables you to select the mode sets to be included to define the rate-changing mode to use when transmitting audio RTP frames using the Fixed Rate mode. This value is used to identify a particular (IANA registered) encoding/payload format (along with any additional parameters such as clock-rate, number of channels, etc.). The value range is from 96 to 127.

Fixed Rate: Enables you to specify the codec-rate to use for AMR codec when operating in "Fixed-Rate" mode where Include Mode Set is selected and at lease one Mode Set has been selected from the available list.

Rate-Change Mode: Enables you to specify the codec rate-switching mode to use for AMR codec. The available switching rates are: Priority, Fixed-Rate, Peer-Requested, and Stress.

AMR-wb — AMR-wb Configuration: Provides access to AMR-wb Configuration settings.

RTP Payload Type: Enables you to set a payload-type value. This value is used to identify a particular (IANA registered) encoding/payload format (along with any additional parameters such as clock-rate, number of channels, etc.). The value range is from 96 to 127.

Octet Alignment: Provides the ability to configure the octet-alignment mode which is signalled (to the peer) and used for client-initiated sessions/calls utilizing the AMR-wb codec. AMR-wb octet-alignment is outlined further in RFC 4867.

Include Mode Set and Mode Set: Enables you to select the mode sets to be included to define the rate-changing mode to use when transmitting audio RTP frames using the Fixed Rate mode. This value is used to identify a particular (IANA registered) encoding/payload format (along with any additional parameters such as clock-rate, number of channels, etc.). The value range is from 96 to 127.

Fixed Rate: Enables you to specify the codec-rate to use for AMR codec when operating in "Fixed-Rate" mode where Include Mode Set is selected and at lease one Mode Set has been selected from the available list.

Rate-Change Mode: Enables you to specify the codec rate-switching mode to use for AMR codec. The available switching rates are: Priority, Fixed-Rate, Peer-Requested, and Stress.

DTMF — DTMF Configuration: Provides access to DTMF Configuration settings.

RTP Payload Type: Enables you to set a payload-type value. This value is used to identify a particular (IANA registered) encoding/payload format (along with any additional parameters such as clock-rate, number of channels, etc.). The value range is from 96 to 127.

G722.1 — G722.1 Configuration: Provides access to G722.1Configuration settings.

RTP Payload Type: Enables you to set a payload-type value. This value is used to identify a particular (IANA registered) encoding/payload format (along with any additional parameters such as clock-rate, number of channels, etc.). The value range is from 96 to 127.

Bit Rate: Provides the ability to configure the bit-rate that is signalled (to the peer) and used for encoding/decoding G722.1 payloads on client-initiated sessions/calls. G722.1 bit-rates are further outlined in RFC 5577.

ILBC — ILBC Configuration: Provides access to ILBC Configuration settings.

RTP Payload Type: Enables you to set a payload-type value. This value is used to identify a particular (IANA registered) encoding/payload format (along with any additional parameters such as clock-rate, number of channels, etc.). The value range is from 96 to 127.

Speex — Speex Configuration: Provides access to Speex Configuration settings.

RTP Payload Type: Enables you to set a payload-type value. This value is used to identify a particular (IANA registered) encoding/payload format (along with any additional parameters such as clock-rate, number of channels, etc.). The value range is from 96 to 127.

Variable Bit Rate: Enables the variable bit-rate mode of the Speex codec to be configured. Available options are On, Off and VAD. This parameter is further covered in RFC 5574.

Speex-wb — Speex-wb Configuration: Provides access to Speex-wb Configuration settings.

RTP Payload Type: Enables you to set a payload-type value. This value is used to identify a particular (IANA registered) encoding/payload format (along with any additional parameters such as clock-rate, number of channels, etc.). The value range is from 96 to 127.

Variable Bit Rate: Enables the variable bit-rate mode of the Speex-wb codec to be configured. Available options are On, Off and VAD. This parameter is further covered in RFC 5574.

Connection

The Connection sub-category under the Configuration tab enables you to configure the SIP connection.

The settings available on this tab are only accessible while the SIP client is not currently registered.

Connection configuration

User name: The name (or number) for which this phone will be registered on the SIP server.

Domain: The domain for which this phone will be registered on the SIP server.

SIP server IP address: The IP address where the SIP server is located. Supports specification of either IPv4 dotted-decimal and IPv6 colon-hexadecimal addresses.

SIP server IP port: The IP port where the SIP server is located.

Contact IP address: The IP address where this SIP client is located. Supports specification of either IPv4 dotted-decimal and IPv6 colon-hexadecimal addresses.

Contact IP port: The IP port where this SIP client is located.

When multiple instances of the IMS-SIP client are running in the same PC, take care to specify different Contact IP port for each instance. For example: use 5080 for first instance and 6000 for second instance.

Display name: The name used in the "From:" header for the SIP message.

Password: The password used for authentication with the SIP server. This value is only applicable to MD5/digest Authentication.

Authentication name: The name used for authentication with the SIP server. This value is only applicable to MD5/digest Authentication.

SRTP: Sets the desired Secure Real-Time Transfer protocol.

Provides the following options:

    • None

    • Force

    • Prefer

Transport: Sets the desired transport protocol. This setting must match how the SIP server is set. For successful VoIP connections, this setting must match the transport type used by the peer VoIP client.

Provides the following options:

    • UDP

    • TCP

Expire time (Sec): Specifies the duration/lifetime (in seconds) that the Client requests for a registration, during registration establishment. For example: This is the value indicated in the "Expires" header of the SIP REGISTER message. Note that the client application automatically attempts to register again, once the current registration expires. (This value must be greater than zero.)

Allow Distinct RTCP Ports: Configures whether to enable specification of distinct RTCP port-ranges for Audio/Video media. (In other words, whether to enable non-default RTCP port mapping or pairing or, if disabled, to use the default RTCP port-mapping algorithm).

Audio RTP Port Range: Specifies the upper and lower bound of the port-range used for audio RTP transfer during VoIP sessions.

Min (left numeric box): Use the arrows on the left numeric box to increment the lower-bound of the port-range.

Max (right numeric box): Use the arrows on the right numeric box to increment the upper-bound of the port-range.

Video RTP Port Range: Specifies the upper and lower bound of the port-range used for video RTP transfer during VoIP sessions.

Min (left numeric box): Use the arrows on the left numeric box to increment the lower-bound of the port-range.

Max (right numeric box): Use the arrows on the right numeric box to increment the upper-bound of the port-range.

Audio RTCP Port Range: Specifies the upper and lower-bound of the port range to be used for audio RTCP transfer during established VoIP calls.

Min (left numeric box): Use the arrows on the left numeric box to increment the lower-bound of the port-range.

Max (right numeric box): Use the arrows on the right numeric box to increment the upper-bound of the port-range.

Video RTCP Port: Specifies the upper and lower-bound of the port-range to be used for video RTCP transfer during established VoIP calls.

Min (left numeric box): Use the arrows on the left numeric box to increment the lower-bound of the port-range.

Max (right numeric box): Use the arrows on the right numeric box to increment the upper-bound of the port-range.

The audio/video RTP port-range must be in the range [10000-50000].

The defined audio and video port-ranges must not overlap.

Each range must have a difference between max-port and min-port of at least 20.

Each port-range min/max value must be set to an even number.

Changes to the port-range settings are only available while the SIP client is not currently registered.

The audio/video RTCP port-range are only enabled when Allow Distinct RTCP Ports is checked.

File Locations

Audio files

Record file name: Specifies the file name of the .wav file to be recorded.

Record file location: Specifies the directory path to the file name specified above in the Record file name field. You can also use the browse button to specify the file location.

Test file name location: Specifies the directory path to the audio test file you wish to play (during VoIP calls) when you select the Send_Test option, available in the audio part of the Audio Video tab.

Video video

Record file name: Specifies the file name of the .avi file to be recorded.

Record file location: Specifies the directory path to the file name specified above in the Record file name field. You can also use the browse button to specify the location.

Test file name location: Specifies the directory path to the video test file you wish to play (during video calls) when you select the SendTest option, available in the Video part of the Audio Video tab). File must be 8kHz or 16kHz sample rate wav.

: Use this button to locate the files above.

The “.wav” and “.avi” filename extensions are not required in the Record file name audio and video parameters respectively. The application will automatically enforce these extensions.

The Record file name setting(s) are treated as a base file-name. When a recording is started the application automatically appends a time-stamp value to the base file-name, such that each recording will have a different filename.

General

General Configuration

Use session description protocol (SDP) : Enables you to set whether or not SDP is used for VoIP call setup.

Enable Session Timer: Enables you to set whether or not to use session-timer functionality to subsequently initiated/updated sessions. the session timer can be set from 90 to 86400 seconds.

Session Timer Mode: Enables you to set the mode to UAC or UAS.

Call Forwarding

Forwarding Mode: Configures the current call-forwarding behavior.

Forwarding Mode | Description
Off | No call forwarding is performed
When On-Call | call-forwarding is invoked when receiving an incoming call-setup request (SIP INVITE) when at least one of the call-lines are in a non-idle state
Always | call-forwarding is invoked when receiving any incoming call-setup requests (SIP INVITEs)

Forwarding URI: Controls the target forwarding URI to use when call-forwarding is invoked. When forwarding is enabled, your entered URI is implicitly translated into a SIP URI form, which is used as the target forwarding URI.

Forwarding URI format | Example Behavior
 | Example URI | Implicitly translated form
<user> | +11234567890 | translated to SIP URI – (by pre-pending “sip:” and combining configured <client_domain> for example: sip:+11234567890@<client_domain>
<user>@<host> | +11234567890@agilent.com | translated to SIP URI (by pre-pending “sip:”) for example: sip:+11234567890@agilent.com
sip:<user>@<host> | sip:+11234567890@test.3gpp.com | No translation performed, URI used verbatim: for example: sip:+11234567890@test.3gpp.com

1. Changing the value of Forwarding URI implicitly disables the Forwarding Mode setting. Therefore, changes to Forwarding URI should be applied before the Forwarding Mode is changed/enabled.

2. If the forwarding is invoked and the URI translation fails, the client reports an error in the Error-Log buffer.

Provisional Ack (PRACK) Config

PRACK Enabled: Select this option to enable the provisional responses to be explicitly acknowledged during session-establishment procedures, to process the various states of the transaction. The current uses of provisional responses are limited to initial session-establishment using the INVITE method.

Precautions

QoS Preconditions Enabled: Select this option to enable/disable functionality associated with the “qos” precondition mechanism. The precondition framework (as associated with the “qos” precondition) is outlined in RFC 3312.

QoS

Differentiated services code point (DSCP): Sets the DSCP used for VoIP.

On MS Windows 7:

  • If the DSCP value is set to > 40, the protocol stack value automatically (internally) reverts to 56.

  • If the DSCP value is set to < 41, the protocol stack value automatically (internally) reverts to 40.

Enable Audio: Select this option to enable QoS feature for audio RTP packets.

Enable Video: Select this option to enable QoS feature for video RTP packets.

Video

Video streaming settings

Camera: Enables you to select the camera (output video device) you wish to use.

If no hardware resource exists, this setting is not accessible.

Configure: Enables some basic configuration of the selected video output device. For example: brightness

Resolution: Sets the required resolution for the currently transmitted video.

Supported Resolutions: QCIF, CIF, QVGA, VGA, SVGA, XVGA, 720P

Frame rate: Enables configuration of the video capture frame-rate. The range of values available is: 5-30.

Bitrate: Enables configuration of the maximum bit-rate associated with video-capture from the video input device (and transmitted over RTP during a VoIP connection). The range of values available is: 1-4096 (kbps).

Use Virtual Device: Enables you to specify whether to use a virtual video device. When this option is enabled, the “Camera” setting is not accessible.
If no physical camera device is detected/available when the application is first loaded, this setting shall be implicitly enabled and unchangeable. Otherwise, this setting can only be accessed/modified when the client application is not currently registered to an IMS-SIP Server.

Video Codec Config: Provides access to codec-specific video parameters.

General

Video codec configuration

Available codecs: Enables you to specify the active video codec-set (included in SDP Offers).

Supported codecs are: H.263, H.263-1998, H.264

Codec Prioritization: Enables arrange by priority the selected codec. Select the codec you want to move and use the arrows to set the priority location in the list.

Modification of the following features are only possible when you are not currently on a VoIP call:

Camera, Resolution, and Video Codec Config.

H.263

H.263 Configuration

QCIF: Select this option to enable resolution for the currently transmitted video. Resolution can be set from 1 to 32 MPI

CIF: Select this option to enable resolution for the currently transmitted video. Resolution can be set from 1 to 32 MPI

H.263-1998

H.263-1998 Configuration

QCIF: Select this option to enable resolution for the currently transmitted video. Resolution can be set from 1 to 32 MPI

CIF: Select this option to enable resolution for the currently transmitted video. Resolution can be set from 1 to 32 MPI

H.264

H.264 Configuration

Profile Level ID: Select this option to specify whether to include H.264 Profile Level ID attribute information in SDP Offers.

Supported levels are: Profile ID 1, Profile ID 1B, Profile ID 11, Profile ID 12, Profile ID 13, Profile ID 2, Profile ID 21, Profile ID 22, Profile ID 3, Profile ID 31, Profile ID 32, Profile ID 4

Packetization Mode: Select this option to specify the H.264 Packetization Mode.

Supported modes are: 0 to 1


Client API Reference

Last Updated: 2014-06-02

This book provides details of the API connectivity for the E6966B IMS-SIP Client Emulator. This API provides you with the ability to automate control of all aspects of the Client Application.

The Client must be running in order to use this API.

The Client API control is provided by the following .NET-based DLL: Agilent.ImsSip.ClientComm.dll.

This DLL is provided as part of the E6966B IMS-SIP Client Emulator installation and can be located as follows:

  • For Windows XP:
    C:\Program Files\Agilent\E6966B\API Tools\Agilent.ImsSip.ClientComm.dll

  • For Windows 7 (64-bit):
    C:\Program Files (x86)\Agilent\E6966B\API Tools\Agilent.ImsSip.ClientComm.dll

See Also

Alphabetical List of Methods (Client)

Interfaces by Category-Client

Reference of Enumerated Types (Client)

Example API Usage (Client)

COM Wrapper

COM Type/Class Identifiers (Client)

Example Code Using COM Interface (Client)

Using the COM Interface (Client)


Alphabetical List of Methods (Client)

Last Updated: 2014-06-02

  • AddErrors

  • AddResults

  • AmrParms

  • AmrWbParms

  • Answer

  • Audio

  • AudioSendTest

  • AudioStartRecord

  • AudioStopRecord

  • AudioStopTest

  • CallLineParams

  • CodecConfig_(Audio)

  • CodecConfig (Video)

  • ClearDetail

  • ClearErrors

  • ClearLast

  • ClearMaximum

  • ClearReceivedMessage

  • ClearResults

  • Close

  • Dial

  • DtmfParms

  • FileLocations

  • G7221Parms

  • GetAudioCodecParmCollection

  • GetAvailableAudioTxCodecs

  • GetCurrentAudioTxCodec

  • GetVideoCodecParmCollection

  • H263Parms

  • H263_1998Parms

  • H264Parms

  • IIlbc1Parms

  • HangUp

  • Hold

  • Initialize_(IComponentControl)

  • Initialize_(IConnection)

  • Qos

  • Reject

  • Register

  • ResetToDefaults

  • RevertToDefaultLevels

  • SendDefault3gppMessage

  • SendDefault3gpp2Message

  • SendMessage

  • SessionForwarding

  • SessionTimer

  • SetCurrentAudioTxCodec

  • Show

  • SpeexParms

  • SpeexWbParms

  • Uninitialize

  • Unregister

  • Video

  • VideoSendLocal

  • VideoSendTest

  • VideoStartRecord

  • VideoStopLocal

  • VideoStopRecord

  • VideoStopTest

  • VideoViewLocal

  • VideoHideLocal


Example API Usage (Client)

Last Updated: 2014-06-02

This section outlines how to use the provided Agilent.ImsSipClientComm.dll to control a running instance of the E6966B IMS-SIP Client Emulator application.

The provided API is intended for use by .NET-based applications, and provides a convenient wrapper to utilize a WCF interface for controlling the IMS-SIP Client application.

To access any of the API methods, a reference to the Agilent.ImsSipClientComm.dll needs to be added to the .NET project/application calling the API.

The following example shows the basic method calls for initializing the WCF interface connection and performing a basic VoIP-call establishment activity.

Example [C#]

// the following using statements should be included at the start of the source-code file

using Agilent.ImsSip.ClientComm; // Access to API methods/interfaces

using Agilent.ImsSip.ClientComm.ServiceReferenceSip; // Access to various type definitions

public class MyClass

{

// defining a reference to the interface

private Agilent.ImsSip.ClientComm.API clientAPI;

// initializing the API to connect via WCF to application running on PC at IP address

// 192.168.1.1:8250

public bool Init(void)

{

clientAPI = new Agilent.ImsSip.ClientComm.API();

return clientAPI.Connection().Initialize(“192.168.1.1”, 8250);

}

// closing the API connection

public void UnInit(void)

{

clientAPI.Connection().Close();

clientAPI = null;

}

// attempt to start a call to a remote-peer client and returns whether the call connected

// an example of a remote peerName value is “sip:remote_peer@agilent.com”

public bool CallPeer(string peerName)

{

if (clientAPI != null)

{

clientAPI.ImsVoip().CallLocation = peerName;

clientAPI.ImsVoip().Sdp = true;

clientAPI.ImsVoip().Dial();

System.Threading.Thread.Sleep(5000); // give the remote peer time to answer call

return clientAPI.ImsComponentControl().IsVoipConnected;

}

else

return false;

}

}


Interfaces by Category (Client)

Last Updated: 2014-06-02

This section provides a reference guide for the API provided by the E6966B IMS-SIP Client Emulator Software. The API is logically split into a number of categories, dealing with different areas of functionality. They are listed below:

  • Audio

  • Audio_Analyzer

  • Audio_Codec_Parameters

  • Call_Line_Paramters

  • Client_Connection

  • Component_Control

  • File_Locations

  • Logging

  • Session_Forwarding

  • Session_Timer

  • Signal_Protocol

  • SIP_Connection

  • SMS

  • Video

  • Video_Codec_Parameters

  • VoIP

Audio

The audio interfaces configure all audio features available in the Audio/Video, Configuration, and VoIP tabs displayed when using the E6966B Client User Interface. The following interfaces are available:

  • IAudio - Interface

  • IAudioCodecConfig - Interface

  • IAudioCodecParmCollection - Interface

Audio Analyzer

The IAudioAnalyzer interface controls the audio analyzer features available in the Information_and_Output_Tabs section of the client user interface.

Audio Codec Parameters

The audio codec parameters are configured by using the GetAudioCodecParamCollection (Method) to call the IAudioCodecParmCollection - Interface. This interface provides access to the audio parameter methods:

  • AmrParms (Method)

  • AmrWbParms (Method)

  • DtmfParms (Method)

  • G7221Parms SpeexParms (Method)

  • IIlbcParms (Method)

  • SpeexParms (Method)

  • SpeexWbParms (Method)

which are used to call the individual codec parameter interfaces:

  • IAmrCodecParams - Interface

  • IAmrWbCodecParams - Interface

  • IDtmfCodecParms - Interface

  • IG7221CodecParams - Interface

  • IIlbcCodecParams - Interface

  • ISpeexCodecParams - Interface

  • ISpeexWbCodecParams - Interface

Call Line Paramters

The ICallLineParams interface enables you to configure the Audio Tx Codec setting on the VoIP tab of the client user interface. The following methods are available:

  • GetAvailableAudioTxCodecs (Method)

  • GetCurrentAudioTxCodec (Method)

  • SetCurrentAudioTxCodec (Method)

Client Connection

The IConnection interface to the API enables you to control connection to the Windows Communication Foundation (WCF) API for the Agilent Soft Phone. This provides a remote control connection to the SIP Client Application interface.

Component Control

The IComponentControl interface to the API enables you to control the component main level features.

Configuration

The IConfiguration interface configures the various parameters associated with the SIP client.

Connection

The IConnection interface controls the connection to the WCF API for the Agilent Soft Phone.

File Locations

The IFileLocations interface configures the audio and video file locations and their names.

Logging

The ILog interface controls the various logging features in the Information_and_Output_Tabs section of the client user interface.

QoS

The IQoS interface configures the quality of service.

Session Forwarding

The ISessionForwarding interface controls the call forwarding parameters on the VoIP tab of the client user interface.

Session Timer

The ISessionTimer interface enables you to remotely configure the session timer parameters on the VoIP tab of the client user interface.

Signal Protocol

The ISigProtocol interface controls the signaling protocol features.

SIP Connection

The ISipConnection interface controls the SIP connection features.

SMS

The ISms interface controls the SMS sending and receiving features.

Video

The video interfaces configure all video features available in the Activity_and_Configuration_Tabs of the client user interface. The following interfaces are available:

  • IVideo - Interface

  • IVideoCodecConfig - Interface

  • IVideoCodecParmCollection - Interface

Video Codec Parameters

The video codec parameters are configured by using the GetVideoCodecParamCollection (Method) to call the IVideoCodecParmCollection - Interface. This interface provides access to the video parameter methods:

  • H263Parms (Method)

  • H263_1998Parms (Method)

  • H264Parms (Method)

which are used to call the individual codec parameter interfaces:

  • IH263CodecParams - Interface

  • IH263_1998CodecParams - Interface

  • IH264CodecParams - Interface

VoIP

The IVoip interface controls the sending and receiving of voice and video over an IP link.

See Also

Interfaces by Category (Server)


IAudio - Interface

Interface: IAudio

Configures the audio features.

Methods:

  • RevertToDefaultLevels

  • CodecConfig (Audio)

Properties:

Property | Action | Type | Description
AudioRecordingDirection | [set/get] | MediaRecordingDirectionEnum | Sets or gets which audio direction is captured when performing an audio-recording operation.
MicrophoneIndex | [set/get] | Integer | Set or get an index integer to indicate which microphone is being used. The first item in the list will be index 0.
MicrophoneVolume | [set/get] | Integer | Set or get a value to indicate the desired microphone volume setting.
RepeatPlayback | [set/get] | Integer | Enables configuration of whether to automatically repeat playback, when performing Audio Test-File playback functionality.
SpeakerIndex | [set/get] | Integer | Set or get an index integer to indicate which speakers are being used. The first item in the list will be index 0.
SpeakerVolume | [set/get] | Integer | Set or get a value to indicate the desired speaker volume setting.
UseVirtualAudioDevice | [set/get] | Boolean | Sets Virtual Audio Device On or Off.

See Also

Interface: IConfiguration

AudioCodecEnum

AudioEnhancementEnum


CodecConfig (Method)

Method: CodecConfig (Audio)

CodecConfig()

Provides access to codec-specific audio configuration parameters and parameter-sets.

Arguments

None

Returns

Possible return values are:

IAudioCodecConfig

Returns IAudioCodecConfig Interface reference

See Also

IAudio

GetAudioCodecParmCollection


RevertToDefaultLevels (Method)

Method: RevertToDefaultLevels

void RevertToDefaultLevels ();

Reverts the volume levels for the currently selected audio input and output devices to internally-defined default levels.

Arguments

None

Returns

None

Notes

The client registration-state must be registered. For example: The client must be registered to an IMS-SIP Server before this method can be called successfully.

See Also

Interface: IAudio


Interface: IAudioAnalyzer

Controls the audio analyzer features.

Methods

  • ClearMaximum

  • Show

Properties

Property | Action | Type | Description
Axis | [set/get] | Integer | Set or gets the audio analyzer maximum axis value.
Enable | [set/get] | Boolean | Sets or get a boolean to enable or disable the audio analyzer.
ReadAverage | [get] | Integer | Read the current average value from the last video stream values received.
ReadMaximum | [get] | Integer | Read the current maximum average value that has been recorded since the last ClearMaximum has been called.


ClearMaximum (Method)

Method: ClearMaximum

void ClearMaximum();

Clear the maximum average value that has been recorded.

Arguments

None

Returns

None

See Also

Interface: IAudioAnalyzer

Show


Show (Method)

Method: Show

void Show();

Shows the User Interface tab that contains the audio analyzer.

Arguments

None

Returns

None

See Also

Interface: IAudioAnalyzer

ClearMaximum


IAudioCodecConfig - Interface

Interface: IAudioCodecConfig

Last Updated: 2014-06-02

This interface controls the overall audio-codec configuration of the client.

Methods:

  • GetAudioCodecParmCollection

  • ResetToDefaults

Properties

None

See Also

IAudioCodecParmCollection


GetAudioCodecParamCollection (Method)

Method: GetAudioCodecParmCollection

IAudioCodecParmCollection GetAudioCodecParmCollection(int index)

Provides access to the codec parameter-collection associated with a specific codec parameter-set.

Arguments

Index

[in]

The index of the audio parameter-set for which access is required. (valid values are 0, 1 or 2)

Returns

Possible return values are:

IAudioCodecParmCollection

A reference to the IAudioCodecParmCollection interface for the designated parameter-set index.

See Also

IAudioCodecConfig

IAudioCodecParmCollection


ResetToDefaults - Method

Method: ResetToDefaults

void ResetToDefaults ();

Resets all of the codec-configuration parameters-sets to their default values.

Arguments

None

Returns

None

Notes

None

See Also

IAudioCodecConfig

IVideoCodecConfig


IAudioCodecParmCollection - Interface

Interface: IAudioCodecParmCollection

Last Updated: 2014-06-02

This interface enables you to access and modify a specific Audio-Codec parameter collection or set.

Methods:

  • AmrParms

  • AmrWbParms

  • DtmfParms

  • G7221Parms

  • SpeexParms

  • SpeexWbParms

Properties

Property | Action | Type | Description
IncludeMaxPTime | [set/get] | boolean | Specifies whether to include the “maxptime” parameter when providing audio-media information in SDP offers/answers.
IncludePTime | [set/get] | boolean | Specifies whether to include the “ptime” parameter when providing audio-media information in SDP offers/answers.
MaxPTime | [set/get] | integer | Specifies the value of “maxptime” to be included in SDP offers/answers if the associated “include” setting has been enabled.
PTime | [set/get] | integer | Specifies the value of “ptime” to be included in SDP offers/answers if the associated “include” setting has been enabled.
SelectedAudioCodecs | [set/get] | List< AudioCodecEnum> | Sets/Gets the selected audio codec list that is specified in SDP Offers sent from the client.
SelectedAudioEnhancements | [set/get] | List<AudioEnhancementEnum> | Sets/Gets the selected audio enhancements that are applied during active VoIP sessions.

See Also

IAudioCodecConfig


AmrParms (Method)

Method: AmrParms

IAmrCodecParams AmrParms();

Accesses the AMR Codec collection.

Arguments

None

Returns

Possible return values are:

IAmrCodecParams

Interface to control the AMR (narrowband) Codec Parameters .

See Also

IAmrCodecParams


AmrWbParms (Method)

Method: AmrWbParms

IAmrWbCodecParams AmrWbParms();

Accesses the AMR-Wb Codec collection.

Arguments

None

Returns

Possible return values are:

IAmrWbCodecParams

Interface to control the AMR (wideband) Codec Parameters .

See Also

IAmrWbCodecParams

IAudioCodecParmCollection


DtmfParms (Method)

Method: DtmfParms

IDtmfCodecParams DtmfParms();

Accesses the DTMF Codec collection.

Arguments

None

Returns

Possible return values are:

IDtmfCodecParams

Interface to control the Dtmf Codec Parameters .

See Also

IDtmfCodecParams

IAudioCodecParmCollection


G7221Parms (Method)

Method: G7221Parms

IG7221CodecParams G7221Parms();

Accesses the G7221 Codec collection.

Arguments

None

Returns

Possible return values are:

IG7221CodecParams

Interface to control the G.722.1 Codec Parameters .

See Also

IG7221CodecParams

IAudioCodecParmCollection


IIlbcParms (Method)

Method: IIlbcParms

IIlbcCodecParams IIlbcParms();

Accesses the iLBC Codec collection.

Arguments

None

Returns

Possible return values are:

IIlbcCodecParams

Interface to control the iLBC Codec Parameters .

See Also

IG7221CodecParams

IAudioCodecParmCollection


SpeexParms (Method)

Method: SpeexParms

ISpeexCodecParams SpeexParms();

Accesses the Speex Codec collection.

Arguments

None

Returns

Possible return values are:

ISpeexCodecParams

Interface to control the Speex Codec Parameters .

See Also

ISpeexCodecParams

IAudioCodecParmCollection


SpeexWbParms (Method)

Method: SpeexWbParms

ISpeexWbCodecParams SpeexWbParms();

Accesses the Speex wideband Codec collection.

Arguments

None

Returns

Possible return values are:

ISpeexWbCodecParams

Interface to control the Speex wideband Codec Parameters.

See Also

ISpeexWbCodecParams

IAudioCodecParmCollection


IAmrCodecParams - Interface

Interface: IAmrCodecParams

Last Updated: 2014-06-02

Controls the AMR (narrowband) codec-specific parameters.

Methods:

None

Properties

Property | Action | Type | Description
DynamicRtpPayloadType | [set/get] | Integer | Specifies the dynamic RTP Payload type to use for AMR RTP.
FixedRate | [set/get] | AudioAmrRateEnum | Specify the codec-rate to use for AMR codec when operating in "Fixed-Rate" mode.
IncludeMaxRed | [set/get] | bool | Specify whether to include the "max-red" attribute for AMR codec in the SDP information.
IncludeModeSet | [set/get] | bool | Set or get whether mode-set information is include in the SDP Offer.
IncludeOctetAlignment | [set/get] | bool | Set or get whether octet-alignment information is included in the SDP Offer.
MaxRed | [set/get] | Integer | Specify the value to use for "max-red" when including it in SDP information.
ModeSet | [set/get] | List<AudioAmrRateEnum> | Set or get the configured mode-set (list of rates) specified in the SDP Offer, when including mode-set information.
OctetAligned | [set/get] | Integer | Set or get the configured octet-alignment value that is specified in the SDP Offer, when including mode-set information. The value must either be 0 (bandwidth-efficient mode) or 1 (octet-aligned mode).
RateChangeMode | [set/get] | AudioAmrRateChangeModeEnum | Specify codec rate-switching mode to use for AMR codec.


IAmrWbCodecParams - Interface

Interface: IAmrWbCodecParams

Last Updated: 2014-06-02

Controls the AMR-WB (wideband) codec-specific parameters.

Methods:

None

Properties

Property | Action | Type | Description
DynamicRtpPayloadType | [set/get] | Integer | Specify the dynamic RTP Payload type to use for AMR-WB RTP.
FixedRate | [set/get] | AudioAmrWbRateEnum | Specify the codec-rate to use for AMR codec when operating in "Fixed-Rate" mode.
IncludeMaxRed | [set/get] | bool | Specify whether to include the "max-red" attribute for AMR-WB codec in the SDP information.
IncludeModeSet | [set/get] | bool | Set or get whether mode-set information is included in the SDP Offer.
IncludeOctetAlignment | [set/get] | bool | Set or get whether mode-set information is include in the SDP Offer.
MaxRed | [set/get] | Integer | Specify the value to use for "max-red" when including it in SDP information.
ModeSet | [set/get] | List<AudioAmrWbRateEnum> | Set or get the configured mode-set (list of rates) that is specified in the SDP Offer, when including mode-set information.
OctetAligned | [set/get] | Integer | Set or get the configured octet-alignment value that is specified in the SDP Offer, when including mode-set information. The value must either be 0 (bandwidth-efficient mode) or 1 (octet-aligned mode).
RateChangeMode | [set/get] | AudioAmrRateChangeModeEnum | Specify codec rate-switching mode to use for AMR codec.

See Also

Interfaces by Category-Client


IDtmfCodecParms - Interface

Interface: IDtmfCodecParams

Last Updated: 2014-06-02

interface IDtmfCodecParams

Interface that controls the DTMF parameters.

Methods:

None

Properties

Property | Action | Type | Description
DynamicRtpPayloadType | [set/get] | Integer | Specifies the dynamic RTP Payload type to use for DTMF/telephone-event RTP


IG7221CodecParams - Interface

Interface: IG7221CodecParams

Last Updated: 2014-06-02

Controls the G.722.1 codec-specific parameters.

Methods:

None

Properties

Property | Action | Type | Description
BitRate | [set/get] | AudioG7221BitRateEnum | Sets or gets the bit-rate specified for the codec (and included in the SDP Offer).
DynamicRtpPayloadType | [set/get] | Integer | Specifies the dynamic RTP Payload-type to use for G.722.1 RTP.


IIlbcCodecParams (Interface)

Interface: IILBCCodecParams

Last Updated: 2014-06-02

Controls the ILBC parameters.

Methods:

None

Properties

Property | Action | Type | Description
DynamicRtpPayloadType | [set/get] | Integer | Specifies the dynamic RTP Payload-type to use for iLBC (Internet Low Bitrate) Codec.


ISpeexCodecParams - Interface

Interface: ISpeexCodecParams

Last Updated: 2014-06-02

Controls the Speex (8kHz / narrowband) codec-specific parameters.

Methods:

None

Properties

Property | Action | Type | Description
DynamicRtpPayloadType | [set/get] | Integer | Specifies the dynamic RTP Payload-type to use for Speex RTP.
IncludeVBR | [set/get] | bool | Set or get whether variable bit-rate (VBR) information is included in the SDP offer.
VBR | [set/get] | AudioSpeexVbrEnum | Set or get the configured VBR mode that is specified in the SDP Offer, when including VBR information.


ISpeexWbCodecParams - Interface

Interface: ISpeexWbCodecParams

Last Updated: 2014-06-02

Controls the Speex-wb (16kHz / wideband) codec-specific parameters.

Methods:

None

Properties

Property | Action | Type | Description
DynamicRtpPayloadType | [set/get] | Integer | Specifies the dynamic RTP Payload-type to use for Speex-Wb RTP.
IncludeVBR | [set/get] | bool | Set or get whether variable bit-rate (VBR) information is included in the SDP offer.
VBR | [set/get] | AudioSpeexVbrEnum | Set or get the configured VBR mode that will be specified in the SDP Offer, when including VBR information.


ICallLineParams - Interface

Interface: ICallLineParams

Last Updated: 2014-06-02

This interface enables you to access the Call Line-specific parameters or status.

Methods:

  • GetAvailableAudioTxCodecs

  • GetCurrentAudioTxCodec

  • SetCurrentAudioTxCodec

Properties

Property | Action | Type | Description
ActiveAudioCodec | [get] | AudioCodecEnum | Get the active audio-codec associated with the VoIP call/session line.
ActiveVideoCodec | [get] | VideoCodecEnum | Get the active video-codec associated with the VoIP call/session line.
CallLocation | [set/get] | string | Set or get the contact to be used when a VoIP call is made (or call-transfer performed) for the associated call/session line.
SessionState | [get] | SessionStateEnum | Get the current state associated with the VoIP call/session line.


GetAvailableAudioTxCodecs (Method)

Method: GetAvailableAudioTxCodecs

List<AudioCodecEnum> GetAvailableAudioTxCodecs();

Provides access to the list of audio codec types which are “active” (for example: type which have been agreed within SDP offer/answer exchange) for the associated VoIP call.

Arguments

None

Returns

Possible return values are:

List<AudioCodecEnum> | The list of active/available Tx Audio codecs on the associated call line.
Null | If there are no available (active) codecs, Null may be returned.

See Also

IAudioCodecConfig

AudioCodecEnum

IAudioCodecParmCollection


GetCurrentAudioTxCodec (Method)

Method: GetCurrentAudioTxCodec

AudioCodecEnum GetCurrentAudioTxCodec();

Provides access to the current audio codec type used for transmitted audio-frames.

Arguments

None

Returns

Possible return values are:

AudioCodecEnum

The active transmitting audio codec value for the associated VoIP call line.

See Also

IAudioCodecConfig

AudioCodecEnum

IAudioCodecParmCollection


SetCurrentAudioTxCodec (Method)

Method: SetCurrentAudioTxCodec

void S etCurrentAudioTxCodec(AudioCodecEnum audioCodec);

Specifies current audio codec type to use for the encoding of transmitted audio-frames on the associated VoIP session/call-line.

Arguments

audioCodec

[in]

The audio-codec to use when encoding audio-frames for transmission on the associated VoIP session.

Returns

None

Notes

Only the subset of audio-codecs that have been agreed during SDP offer/answer are available as valid values for the current audio transmission codec. If an invalid value is specified, the change is silently discarded or ignored and the active transmit-codec is not changed.

See Also

ICallLineParams

IAudioCodecConfig

AudioCodecEnum

IAudioCodecParmCollection


IComponentControl - Interface

Interface: IComponentControl

This interface to the client controls the component main level features.

Methods:

None

Properties:

Property | Action | Type | Description
IsRegistered | [get] | Bool | Read if this soft phone is currently registered with the SIP server.
IsVoipConnected | [get] | Bool | Read if this soft phone is currently in a VoIP call with another soft phone.


Method_Initialize

Method: Initialize (IComponentControl)

void Initialize();

Initializes this soft phone user control. This method must be called from the load event of the parent form.

Arguments

None

Returns

None

See Also

IComponentControl

Uninitialize


Method_Uninitialize

Method: Uninitialize

void Uninitialize();

Uninitializes the soft phone user control. This method is called from the from the closing event of the parent form.

Arguments

None.

Returns

None.

Notes

See Also

IComponentControl

Initialize


IConfiguration - Interface

Interface: IConfiguration

This interface provides the ability to configure various parameters associated with the SIP client.

Methods:

  • Audio

  • FileLocations

  • Qos

  • Video

Properties:

None


Method: Audio

IAudio Audio();

Configures the audio settings.

Arguments

None

Returns

Possible return values are:

IAudio

Returns the IAudio Interface reference.

See Also

Interface: IConfiguration

Video

Qos

FileLocations

Audio

Interface: IAudio


Method: FileLocations

IFileLocations FileLocations();

Configures the File Locations settings.

Arguments

None

Returns

Possible return values are:

IFileLocations

Returns the FileLocations Interface reference.

See Also

Interface: IConfiguration

Video

Qos

Audio

Interface: FileLocations


Method: Qos

IQos Qos();

Configures the Qos settings.

Arguments

None

Returns

Possible return values are:

IQos

Returns the IQos Interface reference

See Also

Interface: IConfiguration

Video

FileLocations

Audio

Qos


Method: Video

IVideo Video();

Configures the video settings.

Arguments

None

Returns

Possible return values are:

IVideo

Returns the IVideo Interface reference

See Also

Interface: IConfiguration

Qos

FileLocations

Audio

Video


Interface: FileLocations

Interface: IFileLocations

Configures the audio and video file locations and their names.

Methods:

None

Properties:

Property | Action | Type | Description
AudioRecordFile | [set/get] | String | Set or get the audio recorded file name.
AudioRecordLocation | [set/get] | String | Set or get the audio recorded file path.
AudioTestFile | [set/get] | String | Set or get the audio test file path and name. The wave file format must be either 8/16-bit, mono/stereo and have a sample-rate which is one of the following: 8kHz, 16kHz or 32kHz.
VideoRecordFile | [set/get] | String | Set or get the audio recorded file name.
VideoRecordLocation | [set/get] | String | Set or get the video recorded file path.
VideoTestFile | [set/get] | String | Set or get the video test file path and name. The AVI file format must use an AVI container, where the video is encoded with one of the following codecs: H.263, H.263+ or H.264.

See Also

Interface: IConfiguration

FileLocations

Interface: IVoip

Interface: IAudio

AudioSendTest

VideoSendTest


IQoS - Interface

Interface: IQoS

Configures the quality of service features.

Methods:

None

Properties:

Property | Action | Type | Description
AudioQos | [set/get] | Boolean | Set or get a boolean to enable or disable the audio quality of service.
Dscp | [set/get] | Integer | Set or get a value to for the differentiated services code point.
VideoQos | [set/get] | Boolean | Set or get a boolean to enable or disable the video quality of service.

See Also

Interface: IConfiguration

Audio

Video

IQoS


IConnection - Interface

Interface: IConnection (Client)

Last Updated: 2014-06-02

This interface to the API enables you to control connection to the WCF API for the Agilent Soft Phone.

Methods:

  • Close

  • Initialize

Properties

Property | Action | Type | Description
ErrorInformation | [get] | string | Gets the SIP Client Error Information of the Initialize function. Returns OK if there are no errors from the Initialize function.
ImsSipClientVersion | [get] | string | Gets the SIP Client version number


Method: Close

Method: Close (Client)

bool Close();

Closes the WCF connection to the Agilent SIP Client Application.

Arguments

None

Returns

Possible return values are:

TRUE | The WCF Connection was closed successful.
FALSE | The WCF Connection was not closed successfully.

Notes

Once a WCF connection is opened, it must subsequently be explicitly closed by the external application. Otherwise the IMS Server application Local GUI control may not function properly.

See Also

IConnection

Initialize

ErrorInformation


Method: Initialize

Method: Initialize (IConnection - Client)

bool Initialize(

[Optional, DefaultParameterValue("192.168.1.230")] string Address,

[Optional, DefaultParameterValue(0x203a)] int Port

);

Establishes WCF connection to the Agilent SIP Client Application.

Arguments

Address | [in] | URI location of the Agilent SIP Client. Example 192.168.1.230 or localhost. Optional default URI = 192.168.1.230
Port | [in] | Port number for the communications. Optional default port = 8250

Returns

Possible return values are:

TRUE | The WCF Initialization was successful.
FALSE | The WCF Initialization was unsuccessful. Check ErrorInformation for additional error information.

Notes

Once a WCF connection is opened, it must subsequently be explicitly closed by the external application. Otherwise the IMS Server application Local GUI control may not function properly.

See Also

Interface: IConnection

ErrorInformation

Close


ILogs - Interface

Interface: ILogs

This interface on the SIP Client enables you to control the various logging features.

Note that all messages/responses sent to and from each SIP Client registered with the SIP Server are monitored and logged at the Server. Refer to the ILogging Interface on the SIP Server for more information.

Methods:

  • AddErrors

  • AddResults

  • ClearDetail

  • ClearErrors

  • ClearResults

Properties:

Property | Action | Type | Description
Detail | [get] | String | Read all the information in the detail log. This information contains the signaling information received by the Agilent Soft Phone.
Errors | [get] | String | Read all the information in the error log.
Results | [get] | String | Read all the information in the results log.

Notes:

  1. The Detail, Errors, and Results properties return the most recent log entries, up to a maximum of 8192 characters in size.

  2. The Detail, Errors and Results properties may be cleared by calling their respective Clear functions.

  3. The AddErrors and AddResults methods enable Test Control Application data to be inserted into the Error and Results Logs (for example:“Starting SMS test 101”).


Method: AddErrors

void AddErrors(string Errors);

Adds information to the error log.

Arguments

Errors

[in]

User defined information to add to the error log.

Returns

None

Notes

The AddErrors method enables you to add user specific information to the error log.

See Also

Interface: ILog

AddResults

Errors

ClearErrors


Method: AddResults

void AddResults (string Results);

Adds information to the results log.

Arguments

Results

[in]

User defined information to add to the results log.

Returns

None

Notes

The AddResults method enables you to add user specific information to the results log.

See Also

Interface: ILog

AddErrors

AddResults

Results

ClearResults


Method: ClearDetail

void ClearDetail();

Clears all the information in the detail log.

Arguments

None

Returns

None

Notes

The detail log may be retrieved by reading the property Detail.

See Also

Interface: ILog

Detail


Method: ClearErrors

void ClearErrors();

Clears all the information in the error log.

Arguments

None

Returns

None

Notes

The error log may be retrieved by reading the property Errors.

See Also

Interface: ILog

Errors

AddErrors


Method: ClearResults

void ClearResults();

Clears all the information in the results log.

Arguments

None

Returns

None

Notes

The results log may be retrieved by reading the Results property.

See Also

Interface: ILog

AddResults

Results


ISessionForwarding - Interface

Interface: ISessionForwarding

Last Updated: 2014-06-02

This interface to the API enables access to information about the state of session or call forwarding.

Methods:

  • None

Properties

Property | Action | Type | Description
ForwardingUri | [set/get] | string | Set or get the Call/Session forwarding uniform resource identifier (URI). Note: Changing this value implicitly switches the forwarding mode to "Off".
ForwardingMode | [set/get] | SessionForwardingModeEnum | Set or get the forwarding mode.

See Also

IVoip


ISessionTimer - Interface

Interface: ISessionTimer

Last Updated: 2014-06-02

This interface provides access to the session-timer functionality.

SIP Session-timer behavior is outlined in RFC 4028.

Methods:

  • None

Properties

Property | Action | Type | Description
Enabled | [set/get] | Boolean | Set or get the current state of the periodic session-update capability.
RefreshMode | [set/get] | List<SessionTimerRefreshModeEnum> | Set or get the current state of the refresh mode. Refresh-mode: the "refresher" parameter as outlined in RFC 4028.
TimerValue | [set/get] | Integer | Set or get the interval/timer-value associated with periodic session update/refresh .

See Also

Interfaces by Category-Client


ISigProtocol - Interface

Interface: ISigProtocol

Controls the signaling protocol features.

Methods:

  • ClearLast

Properties:

Property | Action | Type | Description
Allow | [get] | String | Read the Allow information from the last Response or Message received.
Contact | [get] | String | Read the Contact information from the last Response or Message received.
ContentLength | [get] | String | Read the Content Length information from the last Response or Message received.
ContentType | [get] | String | Read the Content Type information from the last Response or Message received.
CSeq | [get] | String | Read the CSeq information from the last Response or Message received.
FromName | [get] | String | Read the From information from the last Response or Message received.
ToName | [get] | String | Read the To information from the last Response or Message received.
Type | [get] | String | Read the Type information from the last Response or Message received.
ViewLast | [set/get] | ViewLastEnum | Set or get the source for the information to be viewed.

Notes:

Response or Message is set by the ViewLast parameter.


Method: ClearLast

void ClearLast();

Clears the information for the last Response or Message received. Response or Message is set by the ViewLast parameter.

Arguments

None

Returns

None

See Also

Interface: ISigProtocol

ViewLast

ViewLastEnum


ISipConnection - Interface

Interface: ISipConnection

Interface to control the SIP connection features. Note that the client must be unregistered before you apply any properties to this interface.

Methods:

  • Register

  • Unregister

Properties:

Property | Action | Type | Description
AudioMaxRtcpPort | [set/get] | Integer | Set or get the audio max RTCP port to be used when registered with the SIP server.
AudioMinRtcpPort | [set/get] | String | Set or get the audio min RTCP port to be used when registered with the SIP server.
AudioMaxRtpPort | [set/get] | Integer | Set or get the audio max RTP port to be used when registered with the SIP server.
AudioMinRtpPort | [set/get] | String | Set or get the audio min RTP port to be used when registered with the SIP server.
AuthenticationName | [set/get] | String | Set or get the authentication name to be used when registered with the SIP server.
ContactIPAddress | [set/get] | String | Set or get the contact IP address that the SIP server uses for this soft phone.
ContactIPPort | [set/get] | Integer | Set or get the contact port number that the SIP server uses for this soft phone.
DisplayName | [set/get] | String | Set or get the display name to be used when registered with the SIP server.
Domain | [set/get] | String | Set or get the Domain to be used when registered with the SIP server.
ExpireTimeSec | [set/get] | Integer | Set or get the expire time in seconds that the SIP server uses for this soft phone.
SipServerIPAddress | [set/get] | String | Set or get the IP address of the SIP server to be used when registering to the SIP server.
SipServerIPPort | [set/get] | Integer | Set or get the port number of the SIP server to be used when registering to the SIP server.
Srtp | [set/get] | SrtpPolicyEnum | Set or get the SRTP policy that the SIP server uses for this soft phone.
StunServerIPAddress | [set/get] | String | Set or get the STUN server IP address that will be used for this soft phone.
StunServerIPPort | [set/get] | Integer | Set or get the STUN server port that will be used for this soft phone.
UseSpecificRTCPPortRanges | [set/get] | Boolean | Set or get whether to apply distinct or specific RTCP port-numbering ranges.
VideoMaxRtcpPort | [set/get] | Integer | Set or get the video max RTCP port to be used when registered with the SIP server.
VideoMinRtcpPort | [set/get] | Integer | Set or get the video max RTCP port to be used when registered with the SIP server.
VideoMaxRtpPort | [set/get] | Integer | Set or get the video max RTP port to be used when registered with the SIP server.
VideoMinRtpPort | [set/get] | Integer | Set or get the video max RTP port to be used when registered with the SIP server.
Transport | [set/get] | TransportEnum | Set or get the transport protocol that will be used between the SIP server and this soft phone.
UserName | [set/get] | String | Set or get the user name to be used when registered with the SIP server.
Password | [set/get] | String | Set or get the password to be used when registered with the SIP server.

See Also

Interfaces by Category-Client


Register (Method)

Method: Register

void Register();

Registers this soft phone with the SIP server.

Arguments

None

Returns

None

Notes

See Also

Interface: ISipConnection

Unregister


Unregister (Method)

Method: Unregister

void Unregister();

Unregisters this soft phone with the SIP server.

Arguments

None

Returns

None

Notes

See Also

Interface: ISipConnection

Unregister


ISms - Interface

Interface: ISms

Last Updated: 2014-06-02

Control the SMS sending and receiving features.

Methods

  • ClearReceivedMessage

  • SendDefault3gppMessage

  • SendDefault3gpp2Message

  • SendMessage

Properties

Property

Action

Type

Description

Application3gpp

[set/get]

Bool

Set or get a boolean to indicate if the sent message should be of type application- vnd.3gpp.sms.

Application3gpp2

[set/get]

Bool

Set or get a boolean to indicate if the sent message should be of type application- vnd.3gpp2.sms.

AutoLoopback

[set/get]

Bool

Auto loopback the received message to the sender.

Default3gppMessage

[set/get]

String

Set or get a value which is the default text-message string to be encapsulated in an encoded default 3gpp.sms message.

Default3gpp2Message

[set/get]

String

Set or get a value which is the default text-message string for the default 3gpp2.sms message.

DelayMSec

[set/get]

Integer

Set or get a value to indicate the amount of time in milliseconds that should be delayed between each repeated message.

PreAppendMessage

[set/get]

String

Set or get the message that is pre-appended to the received message when the received message is looped back to the sender.

ReceivedMessage

[get]

String

Read the previously received SMS messages.

RepeatSend

[set/get]

Bool

Set or get a boolean to indicate if the message should be sent more than one time.

RepeatTimes

[set/get]

Integer

Set or get a value to indicate the number of time the message should be repeated.

SendAsHex

[set/get]

Bool

Set or get a value which indicates if the Send SMS message is in hex or ASCII.

SendTo

[set/get]

String

Set or get the contact to send an SMS message to.

Subtype

[set/get]

String

Set or get a value to indicate the Mime Subtype for the user defined message. See http://www.iana.org/assignments/media-types/.

TextPlain

[set/get]

Bool

Set or get a boolean to indicate if the sent message should be of type text-plain.

Type

[set/get]

String

Set or get a value to indicate the Mime Content Type for the user defined message. See http://www.iana.org/assignments/media-types/.

UserDefined

[set/get]

Bool

Set or get a boolean to indicate if the sent message should be of an user defined type.

SmscMsisdn

[set/get]

String
(digital-string)

Set or get the MSISDN associated with the Short-Message Service-Centre (SMSC) which handles legacy SMS content.

Example: “1234512345”

Note: This MSISDN value should correlate with the value configured in the Agilent IMS-SIP Server application.

SmscPsi

[set/get]

String
(SIP-URI)

Set or get the SIP-URI associated with the Public Service Identity (PSI) of the SMSC which handles interworking of legacy SMS content.

Example: “sip:sc@agilent.com”

Note: This PSI value should correlate with the value configured in the Agilent IMS-SIP Server application.

Notes

The ReceivedMessage property returns the most recent SMS received messages, up to a maximum of 8192 characters in size. The ReceivedMessage property may be cleared by calling the ClearReceivedMessage method.


Method: ClearReceivedMessage

void ClearReceivedMessage();

Clear any previously received SMS messages.

Arguments

None

Returns

None

Notes

See Also

Interface: ISms

SendDefault3gppMessage

SendDefault3gpp2Message

SendMessage


Method: SendDefault3gppMessage

void SendDefault3gppMessage();

Sends the default 3gpp SMS message (defined in Send_Default_3gpp) to the DUT (specified in Send_to ).

Arguments

None.

Returns

None.

See Also

Interface: ISms

ClearReceivedMessage

SendDefault3gpp2Message

SendMessage


Method: SendDefault3gpp2Message

void SendDefault3gpp2Message();

Sends the default 3gpp2 SMS message (defined in Send_Default_3gpp2) to the DUT (specified in Send_to).

Arguments

None.

Returns

None.

See Also

Interface: ISms

ClearReceivedMessage

SendDefault3gppMessage

SendMessage


Method: SendMessage

void SendMessage(string Message);

Sends an SMS message to the current SMS contact (specified in SendTo).

Arguments

Message

[in]

SMS Message to send.

Returns

None

See Also

Interface: ISms

ClearReceivedMessage

SendDefault3gppMessage

SendDefault3gpp2Message


IVideo - Interface

Interface: IVideo

Configures the video features.

Methods

  • CodecConfig (Video)

Properties

Property | Action | Type | Description
BitRate | [set/get] | Integer | Set or get the currently configured maximum bit-rate (in kbps) associated with video-capture. Note: This value must be within the range [1-4096]
CameraIndex | [set/get] | Integer | Set or get and index integer to indicate which camera is being used. The first item in the list will be index 0.
FrameRate | [set/get] | Integer | Set or get the frame-rate associated with streaming video capture/transmission. Note: This value must be within the range [5-30].
IncludeAudio | [set/get] | Boolean | Specifies whether the audio content of a video-file should be included in the transmission, when sending a test video-file to a remote client while on a VoIP connection.
RecordingCodec | [set/get] | VideoCodecEnum | Specifies the codec-type to use when recording incoming video to file.
RepeatPlayback | [set/get] | Boolean | Set or get whether video-file playback will automatically be repeated when the end-of-file (EOF) is reached during playback.
Resolution | [set/get] | VideoResolutionEnum | Set or get a value indicating the video resolution.
UseVirtualVideoDevice | [set/get] | Boolean | Sets virtual device on or off.
VideoRecordingDirection | [set/get] | MediaRecordingDirectionEnum | Sets or gets which video-direction is captured when performing video-recording operation.

Notes

All properties associated with this interface must only be configured when not currently in a VoIP call/connection, otherwise this will result in undefined behavior.

See Also

Interface

Video

VideoResolutionEnum

VideoCodecEnum


CodecConfig (Method) - Video

Method: CodecConfig (Video)

IVideoCodecConfig CodecConfig();

Provides access to codec-specific video configuration parameters and parameter-sets.

Arguments

None

Returns

Possible return values are:

IVideoCodecConfig

Returns IVideoCodecConfig Interface reference.

See Also

    • IVideo

    • IVideoCodecParmCollection

    • IVideoCodecConfig


IVideoCodecConfig - Interface

Interface: IVideoCodecConfig

Last Updated: 2014-06-02

This interface controls the overall video-codec configuration of the client.

Methods:

  • GetAudioCodecParmCollection

  • ResetToDefaults

Properties

None

See Also

IVideoCodecParmCollection


GetVideoCodecParamCollection (Method)

Method: GetVideoCodecParmCollection

IVideoCodecParmCollection GetvideoCodecParmCollection(int index)

Provides access to the codec parameter-collection associated with a specific codec parameter-set. The 'index' argument is used to select which codec parameter-set is being accessed.

Arguments

Index

[in]

The index of the video parameter-set for which access is required.

(valid values are 0, 1 or 2)

Returns

Possible return values are:

IVideoCodecParmCollection

A reference to the IvideoCodecParmCollection interface for the designated parameter-set index.

See Also

IVideoCodecConfig

IVideoCodecParmCollection


ResetToDefaults (Method)

Method: ResetToDefaults

void ResetToDefaults ();

Resets all of the codec configuration parameter sets to their default values.

Arguments

None

Returns

None

See Also

IVideoCodecConfig

IAudioCodecConfig


IVideoCodecParmCollection - Interface

Interface: IVideoCodecParmCollection

Last Updated: 2014-06-02

This interface to the API enables you to access or modify a specific Video-Codec parameter collection (set). .

Methods:

  • H263_1998Parms

  • H263Parms

  • H264Parms

Properties

Property | Action | Type | Description
SelectedVideoCodecs | [set/get] | List< VideoCodecEnum > | Allows configuration of the video-codecs which are enabled within the client (and are included in SDP offers transmitted by the client during session-establishment/reconfiguration).

See Also

IVideoCodecConfig


H263_1998Parms (Method)

Method: H263_1998Parms

H263_1998Parms()

Accesses the H263_1998 Video Codec collection.

Arguments

None

Returns

Possible return values are:

IH263_1998Params

Interface to control the H263_1998 Video Codec Parameters.

See Also

IH263_1998CodecParams


H263Parms (Method)

Method: H263Parms

H263Parms()

Accesses the H263 Video Codec collection.

Arguments

None

Returns

Possible return values are:

IH263_CodecParams

Interface to control the H.263 Video Codec Parameters.

See Also

IH263_1998CodecParams


H264Parms (Method)

Method: H264Parms

H264Parms()

Accesses the H.264 Video Codec collection.

Arguments

None

Returns

Possible return values are:

IH264_CodecParams

Interface to control the H.264 Video Codec Parameters.

See Also

IH264CodecParams

IVideoCodecParmCollection


IH263_1998CodecParams - Interface

Interface: IH263_1998CodecParams

Last Updated: 2014-06-02

Controls the H.263-1998 video codec parameters.

Methods:

None

Properties

Property | Action | Type | Description
CifMpi | [set/get] | Integer | Specifies the CIF Minimum Picture Interval (MPI), (range from 1-32).
IncludeCifMpi | [set/get] | Boolean | Specifies whether to include CIF Minimum Picture Interval (MPI) attribute info in SDP Offers.
IncludeQcifMpi | [set/get] | Boolean | Specify whether to include QCIF Minimum Picture Interval (MPI) attribute info in SDP Offers.
QcifMpi | [set/get] | Integer | Specify the QCIF Minimum Picture Interval (MPI), (range from 1-32).


IH263CodecParams - Interface

Interface: IH263CodecParams

Last Updated: 2014-06-02

Controls the H.263 video codec parameters.

Methods:

None

Properties

Property | Action | Type | Description
CifMpi | [set/get] | Integer | Specifies the CIF Minimum Picture Interval (MPI), (range from 1-32).
IncludeCifMpi | [set/get] | Boolean | Specifies whether to include CIF Minimum Picture Interval (MPI) attribute information in SDP Offers.
IncludeQcifMpi | [set/get] | Boolean | Specify whether to include QCIF Minimum Picture Interval (MPI) attribute infrmationo in SDP Offers.
QcifMpi | [set/get] | Integer | Specify the QCIF Minimum Picture Interval (MPI), (range from 1-32).


IH264CodecParams - Interface

Interface: IH264CodecParams

Last Updated: 2014-06-02

Controls the H.264 video codec parameters.

Methods:

None

Properties

Property | Action | Type | Description
IncludePacketizationMode | [set/get] | Boolean | Specifies whether to include H.264 Packetization Mode attribute information in SDP Offers.
IncludeProfileLevelId | [set/get] | Boolean | Specifies whether to include H.264 Profile Level ID attribute information in SDP Offers.
PacketizationMode | [set/get] | Boolean | Specifies the H.264 Packetization Mode. (values supported: 0,1).
ProfileLevelId | [set/get] | H264ProfileLevelIdEnum | Specifies the H.264 Profile-Level (outlined in H.264 ITU recommendation) to apply to video-coding.


IVoip - Interface

Interface: IVoip

Last Updated: 2014-06-02

Controls the sending and receiving of voice and video over an IP link.

Methods:

  • Answer

  • AudioSendTest

  • AudioStartRecord

  • AudioStopRecord

  • AudioStopTest

  • CallLineParams

  • Dial

  • HangUp

  • Hold

  • Reject

  • SessionForwarding

  • SessionTimer

  • Unhold

  • Update

  • VideoHideLocal

  • VideoSendLocal

  • VideoSendTest

  • VideoStartRecord

  • VideoStopLocal

  • VideoStopRecord

  • VideoStopTest

  • VideoViewLocal

Properties:

Property | Action | Type | Description
AutoAnswer | [set/get] | Bool | Set or get a boolean to indicate if the application should automatically answer incoming calls without operator intervention.
MuteMicrophone | [set/get] | Bool | Set or get a boolean to indicate if the microphone should be muted.
PrackEnabled | [set/get] | Bool | Set or get whether PRACK procedures are enabled/required within the Client, when performing call-establishment signalling.
QosPreconditionsEnabled | [set/get] | Bool | Set or get whether “qos” preconditions are enabled/required within the Client, when performing call-establishment signalling.
ReceivedLoopback | [set/get] | Bool | Set or get a Boolean to indicate if the application should loop the received voice back to the sender.
Sdp | [set/get] | Bool | Set or get a boolean to indicate if the call should use Session Description Protocol within “Initial SDP Offers”.
SelectedAudioCodecParamSet | [set/get] | Integer | Set or get the selected (zero-based) audio-codec parameter set .
SelectedCallLine | [set/get] | Integer | Set or get the (zero-based) currently selected call line.
SelectedVideoCodecParamSet | [set/get] | Integer | Set or get the selected (zero-based) video-codec parameter set .


Method: Answer

void Answer();

Answers an incoming call.

Arguments

None

Returns

None

See Also

Interface: IVoip

Reject

HangUp


Method: AudioSendTest

void AudioSendTest();

Sends the audio that is in the audio test file location.

Arguments

None

Returns

None

Notes

    1. The AudioSendTest method transmits the audio test file over the currently established VoIP link connection encoded with the selected Audio Codec. The test file location is configured in the property AudioTestFile (Interface: FileLocations).

    2. You can create your own audio file using AudioStartRecord and AudioStopRecord methods. The file is automatically saved in the required 16 kHz .wav format.

    3. When the end of the file is reached, the behavior depends on the [Audio] RepeatPlayback setting

      • If repeat-playback is enabled, the file begins again and replays.

      • Otherwise, file playback will complete and the audio-input is taken from the currently configured audio-input device.

    4. Sample audio file(s) already exist and are located here:

        • For Windows XP: C:\Documents and Settings\All Users\Documents\Agilent\IMS-SIP Client\samples\audio

        • For Windows 7: C:\Users\Public\Public_Documents\Agilent\IMS-SIP Client\samples\audio

See Also

Interface: IVoip

AudioStopTest

AudioTestFile (Interface: IFileLocations)

Dial

AudioStartRecord

AudioStopRecord


Method: AudioStartRecord

void AudioStartRecord();

Starts the audio recorder for the current conversation.

Arguments

None

Returns

None

Notes

The AudioStartRecord method starts recording the audio conversation from the currently established VoIP link connection to the recorded file location. The recorded file location is configured in the properties AudioRecordFile and AudioRecordLocation (Interface: FileLocations). Stop the audio recorder for the current conversation using AudioStopRecord method (Interface: IVoip).

The audio file is required to be recorded in a 16kHz mono .wav format.

See Also

Interface: IVoip

AudioRecordFile

AudioRecordLocation

AudioStopRecord

Dial

AudioSendTest

AudioStopTest


Method: AudioStopRecord

void AudioStopRecord();

Stop the audio recorder for the current conversation.

Arguments

None

Returns

None

Notes

See AudioStartRecord method for further details.

See Also

Interface: IVoip

AudioStartRecord

Dial

AudioSendTest

AudioStopTest


Method: AudioStopTest

void AudioStopTest();

Stop sending the audio that is in the audio test file location.

Arguments

None

Returns

None

Notes

See AudioSendTest method for further details.

See Also

Interface: IVoip

IVoip

Dial

AudioSendTest

AudioStartRecord

AudioStopRecord


CallLineParams (Method)

Method: CallLineParams

ICallLineParams CallLineParams(int index)

Provides access to line-specific parameters or status.

Arguments

Index

[in]

Specifies the line number for which parameter or status access is required.

Returns

Possible return values are:

ICallLineParams

Interface to access the Call Line-specific parameters or status .

See Also

IVoip


Method: Dial

void Dial();

Dials the contact listed in the contact location.

Arguments

None

Returns

None

See Also

Interface: IVoip

Reject

HangUp

Answer


Method: HangUp

void HangUp();

Disconnects from the current call.

Arguments

None

Returns

None

See Also

Interface: IVoip

Dial

Reject

Answer


Hold (Method)

Method: Hold

void Hold();

Holds (locally) the current call.

Arguments

None

Returns

None

See Also

Interface: IVoip

Reject

HangUp

Answer


Method: Reject

void Reject();

Rejects an incoming call.

Arguments

None

Returns

None

See Also

Interface: IVoip

Dial

HangUp

Answer


SessionForwarding (Method)

Method: SessionForwarding

ISessionForwarding SessionForwarding();

Provide access to the call/session forwarding functionality.

Arguments

None

Returns

Possible return values are:

ISessionForwarding

A reference to the ISessionForwarding interface to configure the state of forwarding.

See Also

ISessionForwarding


SessionTimer (Method)

Method: SessionTimer

ISessionTimer SessionTimer();

Provides access to the periodic session refresh/update functionality.

Arguments

None

Returns

Possible return values are:

ISessionTimer

A reference to the ISessionTimer interface to configure the state of session timer.

See Also

ISessionTimer


Unhold (Method)

Method: Unhold

void Unhold();

Resume/unhold the currently locally-held call.

Arguments

None

Returns

None

See Also

Interface: IVoip

Reject

HangUp

Answer


Update (Method)

Method: Update

void Update();

Updates the configuration of the current call (via SIP re-INVITE).

Arguments

None

Returns

None

See Also

Interface: IVoip


Method: VideoHideLocal

void VideoHideLocal();

Stops viewing the real time video from the local camera.

Arguments

None

Returns

None

See Also

Interface: IVoip

Dial

VideoViewLocal

VideoSendLocal

VideoStopLocal

VideoSendTest

VideoStopTest


Method: VideoSendLocal

void VideoSendLocal();

Sends the real time video from the local camera to the remote SIP Client on the call.

Arguments

None

Returns

None

Notes

  1. VideoSendLocal sends the real time video from the local camera to the remote SIP client on the call.

  2. The video file must be an AVI file in either RGB888 or YU20 format.

  3. When multiple codecs are selected, the selection method of the actual codec used is outlined in the Session Description Protocol (SDP) standard RFC2327, section 6.

See Also

Interface: IVoip

Dial

VideoHideLocal

VideoViewLocal

VideoStopLocal

VideoSendTest

VideoStopTest


Method: VideoSendTest

void VideoSendTest ();

Sends the video, located in the video test file location, to the remote SIP client in the VoIP call.

Arguments

None

Returns

None

Notes

  1. The VideoSendTest method transmits the video test file over the currently established VoIP link connection encoded with the selected Video Codec. The test file location is configured in the property VideoTestFile (Interface: FileLocations).

  2. The test video loops back and plays again when the end of file is reached.

  3. The video file must be an AVI file in either RGB888 or YU20 format.

  4. Audio is not sent, even if it exists as part of the AVI file transmitted.

See Also

Interface: IVoip

Dial

VideoStopTest

VideoHideLocal

VideoViewLocal

VideoSendLocal

VideoStopLocal


VideoStartRecord

Method: VideoStartRecord

void VideoStartRecord();

Starts the video recorder for the current VoIP connection.

Arguments

None

Returns

None

Notes

  1. The VideoStartRecord method starts recording the incoming/received video stream from the currently established VoIP link/connection to the recorded file location.

  2. The recorded file location is configured in the properties VideoRecordFile and VideoRecordLocation (Interface: FileLocations). A time-stamp is appended to this filename when a recording is started (Each new recording results in a new file.) Stop the video recorder for the current VoIP connection using VideoStopRecord method (Interface: IVoip).

  3. The video file shall be recording using the codec-type specified by the RecordingCodec Property (Interface:IVideo).

See Also

Interface: IVoip

Interface: FileLocations

VideoRecordFile

VideoRecordLocation

VideoStopRecord

Dial

VideoSendTest

VideoStopTest


Method: VideoStopLocal

void VideoStopLocal();

Stops sending the real time video from the local camera.

Arguments

None

Returns

None

See Also

Interface: IVoip

Dial

VideoHideLocal

VideoViewLocal

VideoSendLocal

VideoStopLocal

VideoSendTest

VideoStopTest


VideoStopRecord

Method: VideoStopRecord

void VideoStopRecord();

Stops the video recorder for the current VoIP connection.

Arguments

None

Returns

None

Notes

See VideoStartRecord method for further details.

See Also

Interface: IVoip

VideoStartRecord

Dial

VideoSendTest

VideoStopTest


Method: VideoStopTest

void VideoStopTest();

Stops sending the video that is in the video test file location.

Arguments

None

Returns

None

See Also

Interface: IVoip

Dial

VideoHideLocal

VideoViewLocal

VideoSendLocal

VideoStopLocal

VideoSendTest


Method: VideoViewLocal

void VideoViewLocal();

Views the real time video from the local camera on the local SIP Client Application.

Arguments

None

Returns

None

See Also

Interface: IVoip

Dial

VideoHideLocal

VideoViewLocal

VideoSendLocal

VideoStopLocal

VideoSendTest


Reference of Enumerated Types (Client)

Last Updated: 2014-06-02

This topic provides a reference for all enumerated types defined for the E6966B IMS-SIP Client API.

Client

  • AudioAmrRateEnum

  • AudioAmrWbRateEnum

  • AudioAmrRateChangeModeEnum

  • AudioCodecEnum

  • AudioEnhancementEnum

  • AudioG7221BitRateEnum

  • AudioSpeexRateEnum

  • AudioSpeexVbrEnum

  • AudioSpeexWbRateEnum

  • H264ProfileLevelIdEnum

  • MediaRecordingDirectionEnum

  • SessionForwardingModeEnum

  • SessionStateEnum

  • SessionTimerRefreshModeEnum

  • SrtpPolicyEnum

  • TransportEnum

  • VideoCodecEnum

  • VideoResolutionEnum

  • ViewLastEnum


AudioAmrRateEnum (Enumerated Type)

Enumerated Type: AudioAmrRateEnum

public enum AudioAmrRateEnum

{

Amr4750,

Amr5150,

Amr5900,

Amr6700,

Amr7400,

Amr7950,

Amr10200,

Amr12200

}

Field Description

AudioAmrRateEnum defines the enumeration of possible AMR codec-rates (which correlate to mode-set values indicated in the SDP offer) that can be configured.

The following AMR rate enumerated values are defined:

Value | Comment
Amr4750 | AMR (narrowband) 4.75 kbps rate
Amr5150 | AMR (narrowband) 5.15 kbps rate
Amr5900 | AMR (narrowband) 5.9 kbps rate
Amr6700 | AMR (narrowband) 6.7 kbps rate
Amr7400 | AMR (narrowband) 7.4 kbps rate
Amr7950 | AMR (narrowband) 7.95 kbps rate
Amr10200 | AMR (narrowband) 10.2 kbps rate
Amr12200 | AMR (narrowband) 12.2 kbps rate

See Also

CodecConfig_(Audio)


AudioAmrWbRateEnum (Enumerated Type)

Enumerated Type: AudioAmrWbRateEnum

public enum AudioAmrWbRateEnum

{

AmrWb6600 = 0,

AmrWb8850 = 1,

AmrWb12650 = 2,

AmrWb14250 = 3,

AmrWb15850 = 4,

AmrWb18250 = 5,

AmrWb19850 = 6,

AmrWb23050 = 7,

AmrWb23850 = 8

}

Field Description

AudioAmrWbRateEnum defines the enumeration of possible AMR codec-rates (which correlate to mode-set values indicated in the SDP offer) that can be configured.

The following AMR-WB rate enumerated values are defined:

Value | Comment
AmrWb6600 | AMR-WB 6.60 kbps rate
AmrWb8850 | AMR-WB 8.85 kbps rate
AmrWb12650 | AMR-WB 12.65 kbps rate
AmrWb14250 | AMR-WB 14.25 kbps rate
AmrWb15850 | AMR-WB 15.85 kbps rate
AmrWb18250 | AMR-WB 18.25 kbps rate
AmrWb19850 | AMR-WB 19.85 kbps rate
AmrWb23050 | AMR-WB 23.05 kbps rate
AmrWb23850 | AMR-WB 23.85 kbps rate

See Also

IAudioCodecConfig - Interface


AudioAmrRateChangeModeEnum (Enumerated Type)

Enumerated Type: AudioAmrRateChangeModeEnum

public enum AudioAmrRateChangeModeEnum

{

PriorityMode = 0,

FixedRateMode = 1,

PeerRequestedMode = 2,

StressMode = 3

}

Field Description

AudioAmrRateChangeModeEnum defines the enumeration of possible AMR rate change modes.

The rate change-mode specifies the behavior of client audio-stream transmissions with regards to the codec-rate which is contained within the encoded-audio RTP frames.

The following mode rate enumerated values are defined:

Value | Comment
PriorityMode | The client transmits, using a constant rate for successive AMR/AMR-WB RTP frames. The specific rate-value that is selected is the highest priority rate that was agreed between the peer clients during the most recent SDP offer or answer exchange.
FixedRateMode | The client transmits using a constant rate for successive AMR/AMR-WB RTP frames. The specific (fixed) rate that is used is determined by a separate parameter (FixedRate) associated with the AMR/AMR-WB codec-parameters.
PeerRequestedMode | The client transmits using the rate/mode requested by the peer client within the codec- mode-request (CMR) field of received AMR/AMR-WB RTP frames.
StressMode | The client continually cycles through the negotiated mode-set, transmitting successive audio RTP frames with different successive rates or modes.

See Also

IAudioCodecConfig - Interface

CodecConfig_(Audio)


AudioCodecEnum (Enumerated Type)

Enumerated Type: AudioCodecEnum

public enum AudioCodecEnum

{

AudioCodecAmr = 0x62,

AudioCodecAmrwb = 0x63,

AudioCodecDtmf = 0x65,

AudioCodecG722 = 9,

AudioCodecG7221 = 0x79,

AudioCodecG729 = 0x12,

AudioCodecGsm = 3,

AudioCodecIlbc = 0x61,

AudioCodecNone = 0,

AudioCodecPcma = 8,

AudioCodecPcmu = 1,

AudioCodecSpeex = 100,

AudioCodecSpeexwb = 0x66

}

Field Description

AudioCodecEnum defines the types of available audio codec that the SIP client may configure.

The following audio codec enumerated values are defined:

Value | Comment
AudioCodecAmr | Audio Codec AMR
AudioCodecAmrwb | Audio Codec AMR-wb
AudioCodecG722 | Audio Codec G.722
AudioCodecG7221 | Audio Codec G.722.1
AudioCodecG729 | Audio Codec G.729
AudioCodecGsm | Audio Codec GSM 6.10
AudioCodecIlbc | Audio Codec iLBC
AudioCodecPcma | Audio Codec G.711 a-Law
AudioCodecPcmu | Audio Codec G.711 u-Law
AudioCodecSpeex | Audio Codec speex
AudioCodecSpeexwb | Audio Codec speex-wb

See Also

IAudioCodecConfig - Interface

IAudio - Interface

CodecConfig_(Audio)


AudioEnhancementEnum (Enumerated Type)

Enumerated Type: AudioEnhancementEnum

public enum AudioEnhancementEnum

{

AudioEnhancement_AcousticEchoCancellation,

AudioEnhancement_AutomaticGainControl,

AudioEnhancement_VoiceActivityDetection

}

Field Description

AudioEnhancementEnum defines the types of Audio Enhancements that the SIP client may configure.

The following audio enhancement enumerated values are defined:

Value | Comment
AudioEnhancement_AcousticEchoCancellation | Audio Enhancement: Echo Cancellation
AudioEnhancement_AutomaticGainControl | Audio Enhancement: Automatic Gain Control
AudioEnhancement_VoiceActivityDetection | Audio Enhancement: Activity Detection

See Also

IAudioCodecConfig


AudioG7221BitRateEnum (Enumerated Type)

Enumerated Type: AudioG7221BitRateEnum

public enum AudioG7221BitRateEnum

{

G7721_24Kbps,

G7221_32Kbps

}

Field Description

AudioG7221BitRateEnum defines the enumeration of possible bit-rates associated with the G.722.1 audio codec that can be configured.

The following G.722.1 bit-rate enumerated values are defined:

Value | Comment
G7721_24Kbps | 24 kbps rate
G7221_32Kbps | 32 kbps rate

See Also

IAudioCodecConfig - Interface

CodecConfig_(Audio)


AudioSpeexRateEnum (Enumerated Type)

Enumerated Type: AudioSpeexRateEnum

public enum AudioSpeexRateEnum

{

Speex2150,

Speex5950,

Speex8000,

Speex11000,

Speex15000,

Speex18200,

Speex24600,

Speex3950,

SpeexAnyRate

}

Field Description

AudioSpeexRateEnum defines the enumeration of possible bit-rates associated with the Speex (8 kHz / narrowband) audio codec that can be configured.

The following Speex bit-rate enumerated values are defined:

Value | Comment
Speex2150 | Speex (narrowband) 2.15 kbps rate
Speex5950 | Speex (narrowband) 5.95 kbps rate
Speex8000 | Speex (narrowband) 8 kbps rate
Speex11000 | Speex (narrowband) 11 kbps rate
Speex15000 | Speex (narrowband) 15 kbps rate
Speex18200 | Speex (narrowband) 18.2 kbps rate
Speex24600 | Speex (narrowband) 24.6 kbps rate
Speex3950 | Speex (narrowband) 3.95 kbps rate
SpeexAnyRate | Indicate “any rate” is supported

See Also

CodecConfig_(Audio)


AudioSpeexVbrEnum (Enumerated Type)

Enumerated Type: AudioSpeexVbrEnum

public enum AudioSpeexVbrEnum

{

SpeexVbrOff,

SpeexVbrOn,

SpeexVbrVad

}

Field Description

AudioSpeexVbrEnum defines the enumeration of possible values that can be associated with Speex (and Speex-WB) VBR (Variable bit-rate) configuration.

The following Speex VBR enumerated values are defined:

Value | Comment
SpeexVbrOff | VBR disabled
SpeexVbrOn | VBR enabled
SpeexVbrVad | VBR with Voice-Activity-Detection mode

See Also

CodecConfig_(Audio)


AudioSpeexWbRateEnum (Enumerated Type)

Enumerated Type: AudioSpeexWbRateEnum

public enum AudioSpeexWbRateEnum

{

SpeexWb3950,

SpeexWb5750,

SpeexWb7750,

SpeexWb9800,

SpeexWb12800,

SpeexWb16800,

SpeexWb20600,

SpeexWb23800,

SpeexWb27800,

SpeexWb34200,

SpeexWb42200,

SpeexWbAnyRate

}

Field Description

AudioSpeexRateEnum defines the enumeration of possible bit-rates associated with the Speex-wb (16 kHz/wideband) audio codec that can be configured.

The following Speex bit-rate enumerated values are defined:

Value | Comment
SpeexWb3950 | Speex-WB (wideband) 3.95 kbps rate
SpeexWb5750 | Speex-WB (wideband) 5.75 kbps rate
SpeexWb7750 | Speex-WB (wideband) 7.75 kbps rate
SpeexWb9800 | Speex-WB (wideband) 9.8 kbps rate
SpeexWb12800 | Speex-WB (wideband) 12.8 kbps rate
SpeexWb16800 | Speex-WB (wideband) 16.8 kbps rate
SpeexWb20600 | Speex-WB (wideband) 20.6 kbps rate
SpeexWb23800 | Speex-WB (wideband) 23.8 kbps rate
SpeexWb27800 | Speex-WB (wideband) 27.8 kbps rate
SpeexWb34200 | Speex-WB (wideband) 34.2 kbps rate
SpeexWb42200 | Speex-WB (wideband) 42.2 kbps rate
SpeexAnyRate | Indicate “any rate” is supported

See Also

CodecConfig_(Audio)


H264ProfileLevelIdEnum (Enumerated Type)

Enumerated Type: H264ProfileLevelIdEnum

public enum H264ProfileLevelIdEnum

{

ID_1 = 1,

ID_1B = 2,

ID_11 = 3,

ID_12 = 4,

ID_13 = 5,

ID_2 = 6,

ID_21 = 7,

ID_22 = 8,

ID_3 = 9,

ID_31 = 10,

ID_32 = 11,

ID_4 = 12

}

Field Description

H264ProfileLevelIdEnum defines the enumeration of possible H.264 ProfileLevelId values that can be associated with the H.264 video codec.

The following H.264 ProfileLevelId values are defined/available:

Value | Corresponding profile-level-id value (as described in RFC3984)
ID 1 | 0x42800A
ID 1B | 0x42900B
ID 11 | 0x42800B
ID 12 | 0x42800C
ID 13 | 0x42800D
ID 2 | 0x428014
ID 21 | 0x428015
ID 22 | 0x428016
ID 3 | 0x42801E
ID 31 | 0x42801F
ID 32 | 0x428020
ID 4 | 0x428028

See Also

IVideoCodecConfig - Interface


MediaRecordingDirectionEnum (Enumerated Type)

Enumerated Type: MediaRecordingDirectionEnum

public enum MediaRecordingDirectionEnum

{

Both = 3,

RxOnly = 1,

TxOnly = 2

}

Field Description

MediaRecordingDirectionEnum contains the SIP Client alternative recording directions. These values are used to filter (based on direction) the media-content that is captured to file during audio/video record operations performed during an active VoIP session.

The following audio recording direction values are defined:

Value | Comment
Both | Selects both directions.
RxOnly | Selects receive direction only.
TxOnly | Selects transmit direction only.

See Also

AudioRecordFile

IAudioCodecConfig - Interface

IAudio - Interface


SessionForwardingModeEnum (Enumerated Type)

Enumerated Type: SessionForwardingModeEnum

public enum SessionForwardingMode Enum

{

Always = 2,

Off = 0,

WhenOnCall = 1

}

Field Description

SessionForwardingModeEnum contains the SIP Client session forwarding states.

The following session forwarding values are defined:

Value | Comment
Always | Sets session forwarding to always be On.
Off | Sets session forwarding to Off.
When on Call | Sets session forwarding to be On when on a call.

See Also

IVoip


SessionStateEnum (Enumerated Type)

Enumerated Type: SessionStateEnum

public enum SessionState Enum

{

Active = 3,

Dialing = 1,

Idle = 0,

LocalHold = 4,

RemoteHold = 5,

Ringing = 2,

Transferring = 6,

Updating = 7

}

Field Description

SessionStateEnum contains the SIP Client session states.

The following session state values are defined:

Value | Comment
Active | The call-line is currently on an active VoIP session.
Dialing | The client is currently dialing another client on the associated call-line.
Idle | The call-line is currently inactive and available.
LocalHold | The client has placed the call-line on hold.
RemoteHold | The call-line has been placed on hold by the remote client.
Ringing | The call-line has received an incoming call-request and is currently ringing.
Transferring | The client is currently in the process of transferring the call to another client.
Updating | The session on the associated call-line is currently undergoing reconfiguration (for example, due to re-INVITE).

See Also

IVoip


SessionTimerRefreshModeEnum

Enumerated Type: SessionTimerRefreshModeEnum

public enum SessionTimerRefreshMode Enum

{

Uac = 0,

Uas = 1

}

Field Description

SessionTimerRefreshModeEnum contains the SIP Client session timer refresh-mode states. The refresh-mode (as in the "refresher" parameter is outlined in RFC 4028.

The following session timer refresh-mode values are defined:

Value | Comment
Uac | Denotes a "refresher" parameter value of "uac".
Uas | Denotes a "refresher" parameter value of "uas".

See Also

ISessionTimer - Interface


SrtpPolicyEnum (Enumerated Type)

Enumerated Type: SrtpPolicyEnum

public enum SrtpPolicyEnum

{

SrtpPolicyForce,

SrtpPolicyNone,

SrtpPolicyPrefer

}

Field Description

SrtpPolicyEnum defines the types of SRTP policy that the SIP client uses for Sip connections to this soft phone.

The following SrtpPolicy values are defined:

Value | Comment
SrtpPolicyForce | The client can only enable/accept incoming calls that are encrypted, and can only place encrypted outgoing calls.
SrtpPolicyNone | The client can enable/accept both encrypted (SRTP) and unencrypted calls, but can only place unencrypted outgoing calls.
SrtpPolicyPrefer | The client enables/accepts both encrypted and unencrypted incoming calls, and can also place outgoing calls which are either encrypted or unecrypted.

See Also

Srtp


TransportEnum (Enumerated Type)

Enumerated Type: TransportEnum

public enum TransportEnum

{

TransportTcp,

TransportUdp

}

Field Description

TransportEnum defines the types of Transport Protocol that the SIP server uses for this soft phone.

The following Transport values are defined:

Value | Comment
TransportTcp | SIP Connection between SIP server and this soft phone set to TCP/IP.
TransportUdp | SIP Connection between SIP server and this soft phone set to UDP.

See Also

SIP Connection

Transport


VideoCodecEnum (Enumerated Type)

Enumerated Type: VideoCodecEnum

public enum VideoCodecEnum

{

VideoCodecH263 = 0x22,

VideoCodecH2631998 = 0x73,

VideoCodecH264 = 0x7d

VideoCodecNone = 0

}

Field Description

VideoCodecEnum defines the types of Video Codec that the SIP client may configure.

The following video codec enumerated values are defined:

Value | Comment
VideoCodecH263 | Video Codec: H.263
VideoCodecH2631998 | Video Codec: H.263 (1988)
VideoCodecH264 | Video Codec: H.264

See Also

IVideo

IVideoCodecConfig

IVideoCodecParmCollection


VideoResolutionEnum (Enumerated Type)

Enumerated Type: VideoResolutionEnum

public enum VideoResolutionEnum

{

VideoQcif,

VideoCif,

VideoQvga,

VideoVga,

VideoSvga,

VideoXvga,

Video720p

}

Field Description

VideoResolutionEnum defines the types of Video Resolution that the SIP client may configure.

The following Video Resolution values are defined:

Value | Comment
VideoQcif | QCIF Video Resolution
VideoCif | CIF Video Resolution
VideoQvga | QVGA Video Resolution
VideoVga | VGA Video Resolution
VideoSvga | SVGA Video Resolution
VideoXvga | XVGA Video Resolution
Video720p | 720p Video Resolution

Notes

You must select a resolution supported by the camera for proper operation of video output.

See Also

Resolution

Video


ViewLastEnum (Enumerated Type)

Enumerated Type: ViewLastEnum

public enum ViewLastEnum

{

Message,

Response

}

Field Description

ViewLastEnum defines the ISigProtocol message type to query.

The following values for this enumerated type are defined:

Value | Comment
Message | Sets the Signal Protocol type to query Messages
Response | Sets the Signal Protocol type to query Responses

See Also

ViewLast

CLearLast


Using the COM Interface (Client)

Last Updated: 2014-06-02

Scripting languages generally provide dynamic/runtime resolution of Type GUIDs, however some compiled languages more commonly require static-linking/association to the GUID values (for example MS VC++). For languages which require this kind of static-linking against a binary type-library (.tlb) file, as part of the application installation the associated tlb file is provided, along with an example .NET source-code extract of the class ProgIDs and GUID definitions, to aid in utilizing the COM-wrapper interface.

The files are provided in a “COM” directory in the “API Tools” sub-directory associated with the installation and comprise the following files:

  • [E6966B_AppDir]\API Tools\COM\clientcomm_comtypes.tlb

  • [E6966B_AppDir]\API Tools\COM\IDs\ClientComm_ComGuids.vb

  • [E6966B_AppDir]\API Tools\COM\IDs\ClientComm_ComProgIDs.vb

The tlb is also useful, even for developers utilizing dynamic/runtime GUID/ProgID mapping, as it is possible to use Windows-based utilities on the binary tlb file to discern API/interface details of the exported COM interfaces/members.

An example tool which can be used to inspect the tlb file is “OleView.Exe” which is provided as part of the freely available Windows SDK (and also implicitly provided as part of non-express versions of MS Visual Studio).

The design of the COM interface is such that there is a single top-level COM object which you should COM-initialize (as in via CoCreateInstance() and so forth). The top-level class implements the COM_GUID__IF_COM interface (WCF-equivalent interface: IComInterface).

Once this class has been COM-initialized, the API-accessors via this COM interface are almost identical to the .NET-managed interface definitions in terms of hierarchy.

For example, the top-level COM class (which is the only class that can be COM-instantiated directly without an error/exception being thrown in the managed runtime) provides various accessor methods which return references or pointers to implementations of sub-interfaces.

This top-level class is identified in COM by the PROGID value associated with: COM_PROGID__CLS_COM_API.

Top-Level COM Interface (as defined in VB.NET)

''' <summary>

''' Top-Level COM-accessible interface providing access to all sub-interfaces

    ''' of the application.

''' </summary>

''' <remarks></remarks>

<ComVisible(True), Guid(ComGuids.COM_GUID__IF_ICOM)>

<InterfaceType(ComInterfaceType.InterfaceIsDual)>

Public Interface IComInterface

Function ImsAudioAnalyzer() As IAudioAnalyzer

Function Connection() As IConnection

Function ImsSipConnection() As ISipConnection

Function ImsComponentControl() As IComponentControl

Function ImsSms() As ISms

Function ImsSigProtocol() As ISigProtocol

Function ImsConfiguration() As IConfiguration

Function ImsLogs() As ILogs

Function ImsVoip() As IVoip

End Interface

All of the sub-interfaces returned by the method calls in the top-level COM interface (ILogs, IConnection, and so forth) are almost exact COM-based equivalent class re-definitions of the WCF-based equivalents.

The native .NET/WCF interfaces or classes are defined as part of the “NET” namespace within the server-communicator .NET project, whereas the COM-based classes are defined as part of the “COM” namespace in the .NET project as outlined in the table below:

Namespace | Namespace-purpose in the Client-Communicator project
NET | .NET/WCF-based types, interfaces and classes
COM | COM-based types, interfaces and classes

The client-communicator DLL is (purposefully) not dotfuscated, to enable you to have the opportunity to run a reflection tool (such as .NET Reflector) in order to get additional detailed information regarding data-types, interfaces and classes that belong to the COM namespace and have been made COM-visible.

See Also

COM Wrapper

Example Code Using COM Interface (Client)

COM Type/Class Identifiers (Client)

Using the COM Interface (Server)

Example Code Using COM Interface (Server)

COM Type/Class Identifiers (Server)

Application Programming Interface (API) Reference


COM Type/Class Identifiers (Client)

Last Updated: 2014-06-02

The identifiers outlined in this section describe a mapping between a COM-based GUID/PROGID identifier-variable (as defined in the sample code files outlined in Using the COM Interface (Client) and the equivalent WCF-based type. The associated GUID/PROG value (as registered in the Windows Registry) can be found in the “ComGuids” and “ComProgIDs” source-files provided with the application installation, and these values are used to uniquely identify COM objects/types that are registered to the Windows OS.

Mappings:

  • Enum_GUID_Mappings

  • Interface_GUID_Mappings

Enum GUID Mappings

ClientComm_ComGuid.vb variable-name | Equivalent WCF Type
COM_GUID__ENUM_VIEWLAST | ViewLastEnum
COM_GUID__ENUM_SESSION_FORWARDING_MODE | SessionForwardingModeEnum
COM_GUID__ENUM_AUDIO_CODEC | AudioCodecEnum
COM_GUID__ENUM_VIDEO_CODEC | VideoCodecEnum
COM_GUID__ENUM_SESSION_STATE | SessionStateEnum
COM_GUID__ENUM_SESSION_TIMER_REFRESH_MODE | SessionTimerRefreshModeEnum
COM_GUID__ENUM_H264_PROFILE_LEVEL_ID | H264ProfileLevelIdEnum
COM_GUID__ENUM_AUDIO_SPEEX_RATE | AudioSpeexRateEnum
COM_GUID__ENUM_AUDIO_SPEEX_VBR_RATE | AudioSpeexVbrEnum
COM_GUID__ENUM_AUDIO_SPEEXWB_RATE | AudioSpeexWbRateEnum
COM_GUID__ENUM_VIDEO_RESOLUTION | VideoResolutionEnum
COM_GUID__ENUM_AUDIO_AMR_RATE | AudioAmrRateEnum
COM_GUID__ENUM_AUDIO_AMR_RATE_CHANGE_MODE | AudioAmrRateChangeModeEnum
COM_GUID__ENUM_AUDIO_AMRWB_RATE | AudioAmrWbRateEnum
COM_GUID__ENUM_AUDIO_G7221_BITRATE | AudioG7221BitRateEnum
COM_GUID__ENUM_TRANSPORT_TYPE | TransportEnum
COM_GUID__ENUM_SRTP_POLICY | SrtpPolicyEnum
COM_GUID__ENUM_AUDIO_ENHANCEMENT | AudioEnhancementEnum
COM_GUID__ENUM_MEDIA_RECORDING_DIRECTION | MediaRecordingDirectionEnum

Interface GUID Mappings

ClientComm_ComGuid.vb variable-name | Equivalent WCF Type
COM_GUID_IF_ICOM | IComInterface
COM_GUID_IF_ICONNECTION | IConnection
COM_GUID_IF_IAUDIOANALYZER | IAudioAnalyzer
COM_GUID_IF_ICOMPONENT_CONTROL | IComponentControl
COM_GUID_IF_ISIPCONNECTION | ISipConnection
COM_GUID_IF_ICONFIGURATION | IConfiguration
COM_GUID_IF_IAUDIO | IAudio
COM_GUID_IF_IVIDEO | IVideo
COM_GUID_IF_IQOS | IQoS
COM_GUID_IF_IFILELOCATIONS | IFileLocations
COM_GUID_IF_ISMS | ISms
COM_GUID_IF_IVOIP | IVoip
COM_GUID_IF_ILOGS | ILogs
COM_GUID_IF_ISIGPROTOCOL | ISigProtocol
COM_GUID_IF_ISESSIONFORWARDING | ISessionForwarding
COM_GUID_IF_ISESSIONTIMER | ISessionTimer
COM_GUID_IF_IAUDIOCODECCONFIG | IAudioCodecConfig
COM_GUID_IF_IAUDIOCODECPARMCOLLECTION | IAudioCodecParmCollection
COM_GUID_IF_IAMRCODECPARAMS | IAmrCodecParams
COM_GUID_IF_IAMRWBCODECPARAMS | IAmrWbCodecParams
COM_GUID_IF_IG7221CODECPARAMS | IG7221CodecParams
COM_GUID_IF_ISPEEXCODECPARAMS | ISpeexCodecParams
COM_GUID_IF_ISPEEXWBCODECPARAMS | ISpeexWbCodecParams
COM_GUID_IF_IDTMFCODECPARAMS | IDtmfCodecParams
COM_GUID_IF_IVIDEOCODECCONFIG | IVideoCodecConfig
COM_GUID_IF_IVIDEOCODECPARMCOLLECTION | IVideoCodecParmCollection
COM_GUID_IF_IH263CODECPARAMS | IH263CodecParams
COM_GUID_IF_IH263_1998CODECPARAMS | IH263_1998CodecParams
COM_GUID_IF_IH264CODECPARAMS | IH264CodecParams
COM_GUID_IF_ICALLLINEPARAMS | ICallLineParams

Class GUID and ProgID Mappings

Since the Class GUID and ProgID values are used to map to a specific implementation of a COM-visible class (and therefore correlate to an externally-visible .NET class implementation), the GUID and ProgID mappings are not outlined here. They are implemented as opposed to having defined details that can be stated.

However, it should be noted here that these ID mappings are provided in the files available to help you use the COM interface. These files are described in the "Using the COM Interface (Client)" topic and their directory locations are shown here.

See Also

COM Wrapper

Using the COM Interface (Client)

Example Code Using COM Interface (Client)

Using the COM Interface (Server)

Example Code Using COM Interface (Server)

COM Type/Class Identifiers (Server)


Example Code Using COM Interface (Client)

Last Updated: 2014-06-02

The test code below utilizes the COM Interface in VC++code. It performs the following:

  • Initializes various COM-visible interfaces/sub-interfaces.

  • Connects (via COM) to the WCF interface of a running client application

  • Attempts to perform a Registration to an IMS-Server

    Note: It only calls the Register() API method. Therefore, you need to pre-configure, using the E6966B GUI on the client, the relevant parameters so that it can successfully communicate and register to the IMS Server).

  • Waits 5 seconds to allow the client time to complete the registration procedure

  • After this, the Selected Call-Line is switched to Line-1 and the Dial() API method is called to attempt to make a VoIP call.
    Note: Again, you need to ensure that a 2nd client is available as the peer of this call. In addition, ensure that the clients are already pre-configured such that a call can be established manually via the Dial GUI button of the client that is being controlled.

  • The Line-1 Call-Status is polled until it becomes either Active or Idle.

  • The test program then terminates (uninitializing the COM interface).

    Note: The call remains connected after the program terminates.

Test Code Begins Here

#include <stdio.h>

#include <stdlib.h>

#include <atlbase.h> // for USES_CONVERSION

// DEFINEs for the possible COM Type-Library (TLB) file info paths..

#define TLB_SRC_LOCAL 0

#define TLB_SRC_INSTALL_WIN7 1

#define TLB_SRC_INSTALL_WINXP 2

// change this and recompile when changing the path to the TLB...

#define TLB_SRC TLB_SRC_INSTALL_WIN7

#if (TLB_SRC == TLB_SRC_LOCAL)

#import "C:\TFSDevelopment\SwIFT\ImsSipClientCommunicator\ImsSipClientComm\bin\x86\Release\com_typelib.tlb"

#elif (TLB_SRC == TLB_SRC_INSTALL_WIN7)

#import "C:\Program Files (x86)\Agilent\E6966B\API Tools\COM\clientcomm_comtypes.tlb"

#else (TLB_SRC == TLB_SRC_INSTALL_WINXP)

#import "C:\Program Files\Agilent\E6966B\API Tools\COM\clientcomm_comtypes.tlb"

#endif

using namespace Agilent_ImsSip_ClientComm;

IComInterface* comIF = NULL;

IConnection* conn = NULL;

ISipConnection* sipconn = NULL;

IComponentControl *compcontrol = NULL;

IVoip *voipcontrol = NULL;

ILogs *logcontrol = NULL;

/*********************************************************

* InitSubInterfaces()

*********************************************************/

void InitSubInterfaces()

{

HRESULT hr = 0;

printf ("Initing Sub Interfaces\n");

hr = comIF->raw_Connection(&conn);

  if (! SUCCEEDED(hr) )  {
printf("failed to get conn interface!\n");
}

hr = comIF->raw_ImsSipConnection(&sipconn);

  if (! SUCCEEDED(hr) )  {
printf("failed to get sipconn interface!\n");
}

hr = comIF->raw_ImsComponentControl(&compcontrol);

if (! SUCCEEDED(hr) ) { printf("failed to get component-control interface!\n"); }

hr = comIF->raw_ImsVoip(&voipcontrol);

if (! SUCCEEDED(hr) ) { printf("failed to get voip control interface!\n"); }

hr = comIF->raw_ImsLogs(&logcontrol);

  if (! SUCCEEDED(hr) )  {
printf("failed to get log control interface!\n");
}

printf ("Initing Sub Interfaces Complete!\n");

}

/*********************************************************

* GetErrorInfo()

*********************************************************/

void GetErrorInfo(bool showMsgBox)

{

HRESULT hr = 0;

USES_CONVERSION;

CComBSTR mystring;

hr = conn->get_ErrorInformation(&mystring);

if (SUCCEEDED(hr))

{

LPCSTR convertedStr = OLE2CT(mystring);

printf ("succeeded in getting ErrorInformation! (%s)\n", convertedStr);

if (showMsgBox)

MessageBox (NULL, convertedStr, TEXT("Message is..."), MB_OK);

}

else

printf ("failed to get ErrorInformation!\n");

}

/*********************************************************

* Main Routine

*********************************************************/

int main(int argc, char *argv[])

{

char *ip_address_string_ptr;

char *port_num_string_ptr;

int portNumber;

HRESULT hr = 0;

VARIANT_BOOL success = false;

CLSID cls;

// Process the command-line params

if (argc != 3)

{

printf("\n\tUsage - comtest.exe <ip_address_string> <port_number>\n");

return 1;

}

ip_address_string_ptr = argv[1];

port_num_string_ptr = argv[2];

portNumber = atoi(port_num_string_ptr);

// do the COM testing...

hr = CLSIDFromProgID (L"Agilent.E6966B.ImsSipClient.ComAPI", &cls);

hr = CoInitialize(NULL);

if (! SUCCEEDED(hr))

{

printf("failed to CoInitialize()!\n");

return 0;

}

if (SUCCEEDED(hr))

{

hr = CoCreateInstance (cls, NULL, CLSCTX_INPROC_SERVER,

__uuidof(IComInterface), (void **) &comIF);

if (SUCCEEDED(hr))

{

USES_CONVERSION;

CComBSTR mystring;

enum SessionStateEnum sessionState;

InitSubInterfaces();

if (conn != NULL)

{

GetErrorInfo(false);

mystring = ip_address_string_ptr; // L"192.168.1.230";

printf("got a conn ptr!\n");

hr = conn->raw_Initialize(mystring, portNumber, &success);

if (SUCCEEDED(hr))

printf("succeeded in performing initialize!\n");

else

printf("failed to perform initialize()!\n");

GetErrorInfo(false);

}

// ISipConnection control

if (sipconn != NULL)

{

hr = sipconn->raw_Register();

hr = sipconn->raw_Register();

if (SUCCEEDED(hr))

{

printf("register() function called okay!\n");

// give the client time to register... (5 seconds..)

printf("sleeping briefly to allow client time to register...\n");

Sleep(5000);

}

else

printf("failed to call register() function! (0x%08x)\n", hr);

GetErrorInfo(false);

}

// IComponentControl control

if (compcontrol != NULL)

{

VARIANT_BOOL regstatus;

hr = compcontrol->get_IsRegistered(&regstatus);

if (SUCCEEDED(hr))

printf("successfully read isRegistered status (= %d)\n",

(regstatus==VARIANT_TRUE));

else

printf("failed to get isRegistered status! (0x%08x)\n", hr);

}

// IVoip control

if (voipcontrol != NULL)

{

struct ICallLineParams *callLineParams;

// set selected line to line-1

hr = voipcontrol->put_SelectedCallLine(0);

if (! SUCCEEDED(hr))

printf ("failed to set selected voip/call line! (0x%08x)\n", hr);

// get a reference to line-1 CallLineParams

hr = voipcontrol->raw_CallLineParams(0, &callLineParams);

if (! SUCCEEDED(hr))

printf ("failed to get reference to call-line-params! (0x%08x)\n", hr);

if (callLineParams != NULL)

{

// Dial a call on line 1 (and wait for a short time

// polling the line-state until it is answered or fails)

hr = voipcontrol->raw_Dial();

if (! SUCCEEDED(hr))

printf( "failed to dial call! (0x%08x)\n", hr);

do

{

Sleep(1000);

hr = callLineParams->get_SessionState(&sessionState);

if (! SUCCEEDED(hr))

{

printf("failed to read call/line state! (0x%08x)\n", hr);

break;

}

printf ("polling line status... (status = %d)\n", sessionState);

              }
while ((sessionState != SessionStateEnum_Idle)
&&

(sessionState != SessionStateEnum_Active));

}

}

}

else

printf("Failed to create IComInterface! (0x%08x)\n", hr);

}

else

printf("Failed to find CLSID!\n");

CoUninitialize();

if (! SUCCEEDED(hr))

{

printf("failed to CoUninitialize()!\n");

return 0;

}

else

printf ("succeeding in performing CoUninitialize()!\n");

return 0;

}

See Also

COM Wrapper

Using the COM Interface (Client)

COM Type/Class Identifiers (Client)

Using the COM Interface (Server)

Example Code Using COM Interface (Server)

COM Type/Class Identifiers (Server)

Application Programming Interface (API) ReferenceCOM Wrapper


Overview-Conference Server UI

Overview: Conference Server User Interface (UI)

Last Updated: 2014-06-02

The IMS-SIP Server Emulator Software UI can be divided into the following seven areas shown in the figure below:

  1. Main Menu

  2. Register Unregister

  3. Conference Factory URL

  4. Per-Call Call Actions

  5. Per-Participant Call Actions

  6. Participant Information

  7. Logging

  8. Status Strip

1 Main Menu

File - This drop-down menu contains the following options:

  • Load Configuration- Enables you to load a configuration previously saved in your data file folder.

  • Save Configuration- Saves your current configuration to your data file folder.

  • Exit - Contains the option to exit the program.

Configuration - This drop-down menu contains the following options:

  • General Configuration - Enables you to set parameters required to set up the server. See General Configuration for detailed information.

Help - This drop-down menu contains the following options:

  • Help - Opens the help file.

  • About - Opens a window for the E6966B that contains information such as the revision number.

2 Register/Unregister

Provides the client with the ability to initiate SIP Registration and De-registration.

3 Conference Factory URL

Displays the currently configured SIP URI associated with the application .

4 Per-Call Call Actions

Provides access to the following per-call actions:

Terminate call: Performs server-initiated call termination of the conference-call, whereby all of the participants are removed from the conference, then the conference-call is terminated (equivalent to individually removing every participant one-by-one).

Mute/Unmute conference audio: Provides the ability to mute the audio output (from the conference-server) so that audio-received by the participants can be muted/unmuted.

This operation is described as a “mute” operation. However, the actual behavior is to disable multiplexing of media between participants (for audio this acts similar to a mute operation) and therefore affects transfer of all media-streams between conference participants.

5 Per-Participant Call Actions

Provides access to the following per-participant actions.

Hold/Unhold participant: Provides the ability to perform a local-hold operation on a specific participant that is present in the conference-call

Remove participant: Provides the ability to terminate a participants connection to the conference-call.

6 Participant Information

This area displays participant-specific informational items associated with any participants that are currently active on a conference-call, such as user-identity, contact-address, etc..

7 Logging

The Logging-area is comprised of 3 main components: a control-strip, an output-area, and a tab/logging-output selector.

Logging control: Provides logging-controls for the active logging-output category. You can perform the following control actions:

    • Start/Stop Logging

    • Pause/Resume Logging

    • Save captured log data to file

    • Clear Logs

Logging output-area: Displays the logging content associated with the active logging-output category.

Detail Logging: Captures the entire message contents for every SIP method (request/response) which propagates via the application when Detail Logging is active. The call-flow and detailed-log data display is limited to the most-recent N logged items, where N=200.

When the detailed-log is saved to a file, the file contains the entire detailed log from the first entry logged, and is not be subject to the N logged-item cap associated with data display.

Status Logging: Provides general status-update information associated with call state. Status-logging is always-on. The status-log only shows the most-recent S logged status-items, where S=1000.

Error Logging: Provides the reports of erroneous conditions occurring during the execution of the application. For example, if you attempt to save a log-capture to file and there is a permissions error, it is posted to the error-log. Error-logging is always-on. The error-log only shows the most-recent E logged error-items, where E=1000.

Logging Tab: Enable you to select the active logging-output category. Changing the logging-output category using the tabs cause both the logging control-strip and output-areas to be updated.

7 Status Strip

Provides useful information regarding the current status of the client, including: Registration-state, WCF API Port, and line-status for all VoIP lines.

Provides quick-access to various information regarding the current state of the application – for example, whether the application is currently IMS registered, the currently configured WCF port (and whether it is successfully open), and the configured domain-name detailed-logging state.


Configuration

Last Updated: 2014-06-02

Configuration, from the main menu area of the Conference-Server UI, enables you to configure the server in the following categories:

  • General Configuration


General Configuration

Last Updated: 2014-06-02

Selecting Configuration > General Configuration from the main menu area of the Conference-Server UI enables you to configure the following functions:

  • Local_Connection

  • IMS_Server

  • Registration

  • Miscellaneous

Local Connection

IP Addresses - Enables specification of the local IP-address used for the conference-server.

This setting is only configurable while the application is in the DEACTIVATED state.

SIP Port - Enables specification of the local SIP Port used for SIP control-plane signaling.

This setting is only configurable while the application is in the DEACTIVATED state.

Transport - Enables specification of the transport-type used for SIP control-plane signaling.

Supported Transport-Protocol Types: UDP and TCP.

This setting is only configurable while the application is in the DEACTIVATED state.

WCF Port - Enables specification of the port-number associated with WCF communications over which .NET-based WCF remote-control is performed. When this setting is changed the WCF receiver is automatically be restarted – if the port fails to initialize successfully during WCF-initialization, an error shall be posted in the error-log. This setting is only configurable from the user interface.

App Ports 1 - Enables specification of the port-number (UDP) to use for application-internal intercommunications.

This setting is only configurable while the application is in the DEACTIVATED state. .

Audio RTP Ports - Enables specification of the port-range used for local audio RTP and RTCP (over UDP) endpoints. The minimum span of the port-range must be 4xMAX_PARTICIPANTS.

This setting is only configurable while the application is in the DEACTIVATED state.

Video RTP Ports - Enables specification of the port-range used for local audio RTP and RTCP (over UDP) endpoints. The minimum span of the port-range must be 4xMAX_PARTICIPANTS.

This setting is only configurable while the application is in the DEACTIVATED state.

IMS Server

IP Address - Enables specification of the IMS Server IP Address (for SIP control-plane messaging)

This setting is only configurable while the application is in the DEACTIVATED state.

SIP Port - Enables specification of the IMS Server port-number (for SIP control-plane messaging)

This setting is only configurable while the application is in the DEACTIVATED state.

Registration

Username - Enables specification of the username part of the SIP URI associated with the conference-server. The value specified by this setting is used to SIP REGISTER the conference-server to the IMS-Server application.

This setting is only configurable while the application is in the DEACTIVATED state.

Domain - Enables specification of the domain part of the SIP URI associated with the conference-server. The value specified by this setting is used to SIP REGISTER the conference-server to the IMS-Server application.

This setting is only configurable while the application is in the DEACTIVATED state.

Miscellaneous

Automatically terminate conference call when call-creator leaves - Selecting this check box configures the server to terminate the conference call when the call-creator leaves the call.


Conference-Server API Reference

Last Updated: 2014-06-02

This book provides details of the API connectivity for the E6966B IMS-SIP Conference-Server Emulator. This API provides you with the ability to automate control of all aspects of the Conference-Server Application.

The Conference-Server must be running in order to use this API.

The Conference-Server API control is provided by the following .NET-based DLL: Agilent.ImsSip.ConfServerComm.dll.

This DLL is provided as part of the E6966B IMS-SIP Conference-Server Emulator installation and can be located as follows:

  • For Windows 7 (64-bit):
    C:\Program Files (x86)\Agilent\E6966B\API Tools\Agilent.ImsSip.ConfServerComm.dll

See Also

Alphabetical List of Methods (Conference-Server)

Client Interfaces by Category (Conference-Server)

Reference of Enumerated Types (Conference-Server)

COM Wrapper

COM Type/Class Identifiers (Conference-Server)

Using the COM Interface (Conference-Server)


Alphabetical List of Methods (Conference-Server)

Last Updated: 2014-06-02

  • BlockConfCallOutput

  • ClearAll

  • ClearDetail

  • ClearError

  • ClearStatus

  • Close

  • HoldParticipant

  • Initialize

  • LoadConfigurationData

  • ReadError

  • ReadStatus

  • Register

  • RemoveParticipant

  • SaveConfigurationData

  • SaveDetail

  • SaveError

  • SaveStatus

  • StartDetailLog

  • StopDetailLog

  • TerminateCall

  • UnblockConfCallOutput

  • UnholdParticipant

  • Unregister


Interfaces by Category (Conference-Server)

Last Updated: 2014-06-02

This section provides a reference guide for the API provided by the E6966B IMS-SIP Conference-Server Emulator Software. The API is logically split into a number of interfaces, dealing with different areas of functionality. They are listed below:

  • Application

  • Call Paramters

  • Configuration

  • Connection

  • Logging

  • Status

Application

The IApplication interface to the API provides the ability to register/unregister the conference-server, and query high-level properties of the application with the following parameter methods:

  • Register

  • Unregister

Call Control

The ICallControl interface to the API provides access to call-control functionality associated with a conference-call, or the participants on a conference-call with the following parameter structures and methods:

  • ConfParticipantInfoStruct

  • TerminateCall

  • RemoveParticipant

  • HoldParticipant

  • UnholdParticipant

  • BlockConfCallOutput

  • UnblockConfCallOutput

Configuration

The IConfiguration interface configures the various parameters associated with the conference-server with the following methods:

  • LoadConfigurationData

  • SaveConfigurationData

Connection

The IConnection interface controls the connection to the WCF API for the IMS Conference-Server application with the following parameter methods:

  • Close

  • Initialize

Logging

The ILogging interface controls access to the various logging modules that track various IMS-SIP operations and results with the following methods:

  • ClearAll

  • ClearDetail

  • ClearError

  • ClearStatus

  • ReadError

  • ReadStatus

  • SaveDetail

  • SaveError

  • SaveStatus

  • StartDetailLog

  • StopDetailLog

Status

The IStatus interface provides the ability to configure various parameters associated with the conference-server.

See Also

Interfaces by Category (Server)

Interfaces by Category (Client)


IApplication

Interface: IApplication

Last Updated: 2014-06-02

This interface to the API provides the ability to register/unregister the conference-server, and query high-level properties of the application.

Methods:

  • Register()

  • Unregister()

Properties:

Property | Action | Type | Description
Version | [get] | string | A string containing the runtime version-number of the conference-server application.


Method: Register

Method: Register (Conference-Server)

void Register();

Initiates an attempt to perform registration of the conference-server to an IMS Server.

Arguments

None

Returns

None

Notes

  • The target for the registration (i.e. IP-address, port) and protocol used for registration are part of the general-configuration of the conference-server application and should be properly configured prior to initiating a registration attempt.

  • The progress (and success/failure) of the registration procedure can be determined by querying the AgSipConfRegState property.

  • If the conference-server is currently not in an “Unregistered” state when this action is performed, the action will essentially do nothing.

  • In the case where registration failed, there may also be additional error information present in the application “Error Log”.


Method: Unregister

Method:Unregister (Conference-Server)

void Unregister();

Initiates a de-registration of the conference-server from the IMS server to which it is currently registered.

Arguments

None

Returns

None

Notes

  • If the conference-server is currently not in a “Registered” state, this action will essentially do nothing.

  • The progress of the de-registration procedure can be determined by querying the AgSipConfRegState property.

  • In the case where de-registration failed, there may also be additional error information present in the application “Error Log”.

See Also

IConnection

ErrorInformation

Close


ICallControl - Interface

Interface: ICallControl

Last Updated: 2014-06-02

This interface to the API provides access to call-control functionality associated with a conference-call, or the participants on a conference-call.

Methods:

  • BlockConfCallOutput

  • HoldParticipant

  • RemoveParticipant

  • TerminateCall

  • UnblockConfCallOutput

  • UnholdParticipant

Properties

None


ConfParticipantInfoStruct

Structure: ConfParticipantInfoStruct

Last Updated: 2014-06-02

This structure, available in the Conference-Server API, encapsulates information about a particular session that is currently established between the conference-server and an individual conference-call participant ....

Properties:

Property

Action

Type

Description

FromUri

[get]

 String

The URI for this session which is associated with the originating-party during initial session-establishment.

(i.e. the URI in the “From” header of the initial INVITE).

ToUri

[get]

 String

The URI for this session which is associated with the terminating-party during initial session-establishment.

(i.e. the URI in the “To” header of the initial INVITE).

FromTag

[get]

 String

The dialog-tag for this session which is associated with the originating-party during initial session-establishment.

ToTag

[get]

 String

The dialog-tag for this session which is associated with the terminating-party during initial session-establishment.

CallId

[get]

 String

The Call-ID for this dialog/session which is associated between the two endpoints of this session.

(i.e. the value of the “Call-ID” header of the initial INVITE).

ParticipantUri

[get]

 String

A convenience property which always maps to the URI of the participant associated with this session between the participant and conference-server (regardless of which party initiated the session).

The value of this property, when queried, will be the same as either the value of the “FromUri” or “ToUri” property, depending on which party originally initiated the session.

ParticipantId

[get]

 String

A unique identifier used (and allocated by) the conference-server to uniquely identify the participant associated with this session, which is utilized by other API methods (for example to force a participant into a “hold” state from the conference-server etc..)

ContactAddress

[get]

 String

The Contact-address of the Participant associated with this session.

SessionState

[get]

 SessionStateEnum

The current state of the session (between conference-server and participant).

Fields

None


Method: TerminateCall

bool bool TerminateCall()

Terminates the conference-call (if one is established).

Arguments

None

Returns

Possible return values are:

TRUE | The call was terminated (i.e. the operation completed successfully).
FALSE | The call was not terminated (i.e. the operation failed).

See Also

ICallControll


Method: RemoveParticipant

bool RemoveParticipant(string participantId);

Removes a conference call participant (identified by a unique ID) from a call.

Arguments

participantId

[in]

A call participant (identified by a unique ID).

Returns

Possible return values are:

TRUE | The call participant (identified by a unique ID) was removed from a call.
FALSE | The call participant (identified by a unique ID) was not removed from a call.

Notes

  1. The participantId values associated with particular participants of the conference-call can be determined by querying the ConfCallParticipantInfo property.

See Also

IStatus


Method: HoldParticipant

bool HoldParticipant(string participantId);

Places a conference call participant (identified by a unique ID) on hold.

Arguments

participantId

[in]

A call participant (identified by a unique ID).

Returns

Possible return values are:

TRUE | The call participant (identified by a unique ID) was placed on hold.
FALSE | The call participant (identified by a unique ID) was not placed on hold.

Notes

  1. The participantId values associated with particular participants of the conference-call can be determined by querying the ConfCallParticipantInfo property.

See Also

ICallControll

IStatus


Method: UnholdParticipant

bool HoldParticipant(string participantId);

Performs a resume/unhold operation on the participant identified by the specified ID.

This operation can only be successfully applied to a participant that was previously placed into (and is currently still in) a call-held state (by the conference-server).

Arguments

participantId

[in]

The unique-id value identifying the participant on which to perform the action.

Returns

Possible return values are:

TRUE | The operation succeeded (and the specified participant is actively participating in the conference-call).
FALSE | The operation failed.

Notes

The participantId values associated with particular participants of the conference-call can be determined by querying the ConfCallParticipantInfo property.

See Also

IConfiguration - Interface

IStatus


Method: BlockConfCallOutput

bool BlockConfCallOutput();

This method provides the ability to disable multiplexing of all user-plane media streams at the conference-server, thereby blocking all media from being conferenced between participants.

(ex: all audio, video, etc… will stop being conferenced between participants).

Arguments

None

Returns

Possible return values are:

TRUE | The method executed successfully and multiplexing of user-plane media is disabled at the conference-server.
FALSE | The method failed, and blocking was not applied.

See Also

ICallControll - Interface


Method: UnblockConfCallOutput

bool UnblockConfCallOutput();

This method provides the ability to (re-)enable multiplexing of all user-plane media streams at the conference-server, thereby allowing media to be conferenced between participants.

Arguments

None

Returns

Possible return values are:

TRUE | The method executed successfully and multiplexing of user-plane media is enabled at the conference-server.
FALSE | The method failed.

See Also

IConfiguration - Interface


IConfiguration - Interface

Interface: IConfiguration

Last Updated: 2014-06-02

This interface provides the ability to configure various parameters associated with the conference-server.

Methods:

  • LoadConfigurationData

  • SaveConfigurationData

Properties

Property | Action | Type | Description
AppInternalPort1 | [get/set] | unsigned integer | Set or get the port-number associated with internal application communications
AudioMaxRtpPort | [get/set] | unsigned integer | Set or get the upper-bound value of the audio-port range used by the application.
AudioMinRtpPort | [get/set] | unsigned integer | Set or get the lower-bound value of the audio-port range used by the application.
AutoTerminationState | [get/set] | bool | Set or get a boolean which specifies whether an active conference-call should be implicitly terminated when the host/originator participant leaves the call.
Domain | [get/set] | String | Set or get the domain associated with the conference-server.
LocalIPAddress | [get/set] | String | Set or get the local IP-address utilized by the conference-server.
LocalSipPort | [get/set] | unsigned integer | Set or get the (default) local port used by the conference-server for control-plane signalling.
SipServerIPAddress | [get/set] | String | Set or get the IP-address of the IMS/SIP Server to which the conference-server shall perform registration (and route control-plane signalling).
SipServerIPPort | [get/set] | unsigned integer | Set or get the port used by the IMS/SIP Server for reception of control-plane signalling.
Transport | [get/set] | ProtocolType | Set or get the default protocol/transport-type to utilize for control-plane signalling (between the conference-server and the IMS-server).
UserName | [get/set] | String | Set or get the username associated with the conference-server.
VideoMinRtpPort | [get/set] | unsigned integer | Set or get the upper-bound value of the video-port range used by the application.
VideoMaxRtpPort | [get/set] | unsigned integer | Set or get the lower-bound value of the video-port range used by the application.


Method: LoadConfigurationData

bool LoadConfigurationData(string filename);

Loads configuration data from a previously saved configuration file.

Arguments

string

The file (including fully-qualified path) to load.

Returns

Possible return values are:

TRUE | The configuration file was successfully loaded.
FALSE | The configuration file failed to load correctly.

Notes

  1. It is recommended that the application should be in an unregistered/deactivated state before a configuration file is loaded, to guarantee that the newly loaded configuration is applied immediately.

See Also

IConfiguration


Method: SaveConfigurationData

bool SaveConfigurationData(string filename);

Saves the current application-configuration to a specified file.

Arguments

filename

[in]

The file (including fully-qualified path) which should store the configuration data.

Returns

Possible return values are:

TRUE | The configuration was saved successfully to the specified file.
FALSE | The configuration failed to save correctly.

See Also

IConfiguration - Interface


IConnection - Interface

Interface: IConnection (Conference-Server)

Last Updated: 2014-06-02

This interface to the API enables you to control connection to the WCF API for the IMS Conference-Server application.

Methods:

  • Close

  • Initialize

Properties

Property | Action | Type | Description
ErrorInformation | [get] | string | Gets the SIP Conference-Server error information associated with a previous call to the Initialize/Close functions of this interface. Returns OK if there are no errors from the Initialize function.


Method: Close

Method: Close (Conference-Server)

bool Close();

Closes the WCF connection to the Agilent SIP Conference-Server Application.

Arguments

None

Returns

Possible return values are:

TRUE | The WCF Connection was closed successful.
FALSE | The WCF Connection was not closed successfully.

Notes

Once a WCF connection is opened, it must subsequently be explicitly closed by the external application. Otherwise the application’s local GUI controls may not function properly.

See Also

IServer


Method: Initialize

Method: Initialize (IConnection - Conference-Server)

bool Initialize(

[Optional, DefaultParameterValue("192.168.1.230")] string Address,

[Optional, DefaultParameterValue(8245)] int Port

);

Establishes WCF connection to the Agilent SIP Conference-Server Application.

Arguments

Address | [in] | IP Address location of the application. Example “192.168.1.230” or “localhost”. Optional default value is “192.168.1.230”.
Port | [in] | Port number for the WCF communications. Optional default port = 8245.

Returns

Possible return values are:

TRUE | The WCF Initialization was successful.
FALSE | The WCF Initialization was unsuccessful. Check ErrorInformation for additional error information.

Notes

Once a WCF connection is opened, it must subsequently be explicitly closed by the external application. Otherwise the application’s local GUI controls may not function properly.

See Also

IConnection

ErrorInformation

Close


Method: ClearAll

public void ClearAll();

Clears the Call Flow, Status, and Error logs.

Arguments

None

Returns

None

Notes

  1. The ClearAll method clears all Logging buffers of data. Log buffers may be cleared individually calling the individual clear functions. The Logging buffers on the SIP Conference-Server are: Call-Flow, Status, and Error.

  2. The Logging buffers can be cleared while Logging is started or stopped. When a log buffer is stopped, the SIP Conference-Server does not fill the buffer with log data. Exceptions to this are the Status Log and Error Log, as these are always running while the SIP Conference-Server is activated.

See Also

ILogging

ClearError

ReadError


Method: ClearDetail

public void ClearDetail();

Clears the Conference-Server Detail log.

Arguments

None

Returns

None

Notes

  1. The ClearDetail method clears the Detail Log buffer of data.

  2. The Call-Flow/Detail log contains the details of all incoming and outgoing messages and responses (Register, SMS, VoIP message and responses). The detail stored in the Detail log varies per type of message or response, and lists all message and response fields in detail.

  3. The logging buffers may be cleared while Detail logging is started or stopped. When the Detail logging is stopped, the SIP Conference-Server does not update the Detail buffer with log data.

See Also

ILogging

ClearAll

SaveDetail

StartDetailLog

StopDetailLog


Method: ClearError

public void ClearError();

Clears the Conference-Server Error Log.

Arguments

None

Returns

None

Notes

  1. The ClearError method clears the Error Log buffer of data.

  2. The Error Log contains detail on any application error detected. The detail stored in the Error Log per entry is formatted as follows:

“[“ Timestamp “]” CRLF <log-entry> (CRLF)+

Where (CRLF)+ denotes “at least one” CRLF.

  3. The Error Log buffers can be cleared at any time while the application is running. Error Logging is always enabled when the application is activated.

See Also

ILogging

ClearAll

ReadError

SaveError


Method: ClearStatus

public void ClearStatus();

Clears the Conference-Server Status Log.

Arguments

None

Returns

None

Notes

  1. The ClearStatus method clears the Status Log buffer of data.

  2. The Status Log contains informational/diagnostic output details. The detail stored in the Status Log per entry is formatted as follows:

“[“ Timestamp “]” CRLF <log-entry> (CRLF)+

Where (CRLF)+ denotes “at least one” CRLF.

  3. Status Logging is always active whilst the application is running and can be cleared by the user at any time.

See Also

ILogging

ClearAll

ReadStatus

SaveStatus


Method: ReadError

public string ReadError();

Returns the SIP Conference-Server Error log buffered data.

Arguments

None

Returns

Possible return values are:

String

Error log buffer data

Notes

  1. The Error Log contains the details on any SIP Server error detected. The detail stored in the Error Log per entry is formatted as follows:

“[“ Timestamp “]” CRLF <log-entry> (CRLF)+

Where (CRLF)+ denotes “at least one” CRLF.

  2. The ReadError method reads and returns the current Error Log buffer data. The ReadError method is called to retrieve the current Error Log data for processing. It is recommended that you call this method after each operation is performed within the SIP Conference-Server in order to detect any errors. To save the Error Log buffer data to file use the SaveError method.

  3. Error logging is always enabled whilst the application is running, and can be cleared at any time.

  4. If the total error-log buffer size exceeds the maximum WCF interface response-length, the return value shall be truncated before being returned.

See Also

ILogging

ClearAll

ClearError

SaveError


Method: ReadStatus

public string ReadStatus();

Returns the SIP Conference-Server Status log buffered data.

Arguments

None

Returns

Possible return values are:

String

Status log buffer data

Notes

  1. The Status Log contains the details on any SIP Server error detected. The detail stored in the Status Log per entry is formatted as follows:

“[“ Timestamp “]” CRLF <log-entry> (CRLF)+

Where (CRLF)+ denotes “at least one” CRLF.

  2. To save the Status Log buffer data to file use the SaveStatus method.

  3. Status logging is always enabled whilst the application is running, and can be cleared at any time.

  4. If the total status-log buffer size exceeds the maximum WCF interface response-length, the return value shall be truncated before being returned.

See Also

ILogging

ClearAll

ClearStatus

SaveStatus


Method: SaveDetail

public void SaveDetail(string FileNameAndPath);

Saves the Detail log buffered data to a specified filename on the SIP Conference-Server host machine.

Arguments

FileNameAndPath

[in]

 This is the absolute filename and path to which the Detail Log is saved on the SIP Conference-Server host machine.

Returns

None

Notes

  1. SaveDetail saves the current Detail log buffer data to a specified file.

  2. If the file exists, the operation overwrites the existing file contents. If you only specify a filename, the log is saved in the same location as the remote SIP Server Application.

  3. Logs are saved on the same host as the SIP Conference-Server application.

The Detail/Call Flow logging must have been stopped prior to attempting to save the log content, otherwise the save will not perform successfully.

See Also

ILogging

ClearAll

ClearDetail

StartDetailLog

StopDetailLog


Method: SaveError

public void SaveError(string FileNameAndPath);

Saves the Error log buffered data to a specified filename on the SIP Conference-Server host machine.

Arguments

FileNameAndPath

[in]

This is the absolute filename and path to which the Error log is saved on the SIP Conference-Server host machine.

Returns

None

Notes

  1. If the file exists, the operation overwrites the existing file contents. If you only specify a filename, the log is saved in the same location as the remote SIP Server Application.

See Also

ILogging

ClearAll

ClearError

ReadError


Method: SaveStatus

public void SaveStatus(string FileNameAndPath);

Saves the Status Log buffered data to a specified filename on the SIP Conference-Server host PC.

Arguments

FileNameAndPath

[in]

This is the absolute filename and path to which the Status Log is saved on the SIP Conference-Server host PC.

Returns

None

Notes

  1. If the file exists, the operation overwrites the existing file contents. If you only specify a filename, the log is saved in the same location as the remote SIP Conference-Server Application.

See Also

ILogging

ClearAll

ClearStatus

ReadStatus


Method: StartDetailLog

public void StartDetailLog();

Starts the Detailed/Call-Flow logging module of the application.

Arguments

None

Returns

None

Notes

  1. The Detail/Call Flow Log contains the detail on all incoming and outgoing message and response flows. The detail stored (for each log item) in the Detail/Call Flow Log is:

“[“AbsoluteTimestamp “]” CRLF

“[Elapsed Time =” RelativeTimestamp “]” CRLF

message-content (CRLF)+

  1. Whereby:

  1. RelativeTimestamp is the relative time difference (to millisecond resolution) between log-time of the message compared to the immediately preceeding message

  2. (CRLF)+ denotes “at least one” CRLF character-sequence..

See Also

ILogging

ClearAll

ClearDetail

SaveDetail

StopDetailLog


Method: StopDetailLog

public void StopDetailLog();

Stops the SIP Conference-Server Detail logging module.

Arguments

None

Returns

None

See Also

ILogging

ClearAll

ClearDetail

SaveDetail

StartDetailLog


IStatus

Interface: IStatus

Last Updated: 2014-06-02

This interface provides the ability to configure various parameters associated with the conference-server.

Methods:

None

Properties

Property | Action | Type | Description
AppActivationState | [get] | AgSipConfActivationState | Provides the current activation-state of the conference-server application. (Read-only property)
ConfCallParticipantInfo | [get] | List<ConfParticipantInfoStruct> | Provides a list containing information on all participants that are actively associated with the current conference-call. (Read-only property)
ConfCallStatus | [get] | AgSipConfCallState | Provides the current conference-call state of the application (i.e. whether there is an established conference-call etc..). (Read-only property)
RegistrationStatus | [get] | AgSipConfRegState | Provides the current registration-state of the conference-server (i.e. whether it is currently registered to an IMS server etc..). (Read-only property


Reference of Enumerated Types (Conference-Server)

Last Updated: 2014-06-02

This topic provides a reference for all enumerated types defined for the E6966B IMS-SIP API Conference-Server Emulator Software.

Server

  • AgSipConfActivationState

  • AgSipConfCallState

  • AgSipConfRegState

  • AgSipProtocolType

  • SessionStateEnum

See Also

Alphabetical List of Methods (Conference-Server)

Alphabetical List of Structures (Conference-Server)

Interfaces by Category (Conference-Server)


ProtocolType (Enumerated Type)

Enumerated Type: ProtocolType

public enum ProtocolType

{

TCP = 0,

UDP= 1

}

Field Description

AgSipProtocolType represents the configured network-layer protocol utilized by the conferencing application for exchange of control-plane signalling.

The following SIP Control-Plane Transport-Protocol Types supported with descriptions are defined:

Value | Comment
TCP | Transport Control Protocol
UDP | User Datagram Protocol


AgSipConfActivationState (Enumerated Type)

Enumerated Type: AgSipConfActivationState

public enum AgSipConfActivationState

{

Deactivating = 0,

Deactivated = 1,

Activating = 2,

Activated = 3

}

Field Description

AgSipConfActivationState represents the activation state of the IMS conferencing application. Activation involves preparation of internal data/structures required for conferencing and is implicitly performed prior to registration of the conference-server.

The conferencing application must achieve both of the following before conference-calls can be successfully performed:

  • An activation-state of “activated”,

  • A registration-state of “registered”.

The following activation states are defined:

Value

Comment

Deactivating

The application is in the process of freeing/releasing resources required for call-conferencing.

Deactivated

The application has released internal resources required to facilitate call-conferencing and perform conference-calling.

Activating

Activation of the conferencing-application has been requested and is currently in-progress.

Activated

The application is activated, and has therefore prepared resources required to perform conference-calling.

Note: The registration state of the conference-server application must also be “registered” before conference-calling can be performed.


AgSipConfCallState (Enumerated Type)

Enumerated Type: AgSipConfCallState

public enum AgSipConfCallState

{

Idle = 0,

Establishing = 1,

Established = 2

}

Field Description

AgSipConfCallState represents the current state of the conference-call resource, and denotes whether or not a conference-call is currently taking place.

The following states are defined:

Value | Comment
Idle | The conference-call entity is currently idle. No conference-call is present, and resources has not been assigned for handling a conference-call.
Establishing | The conference-call entity is in the process of assigning/reserving resources for the conference-call and SIP signalling is currently taking place to establish the call.
Established | A conference-call is has been established and is currently active (with at least one participant).

See Also


AgSipConfRegState (Enumerated Type)

Enumerated Type: AgSipConfRegState

public enum AgSipConfRegState

{

Unregistered = 0,

Unregistering = 1,

Registering = 2,

Registered = 3

}

Field Description

AgSipConfRegState represents the current registration-state of the conferencing application to the IMS Server.

The conferencing application must achieve both of the following before conference-calls can be successfully performed:

  • An activation-state of “activated”.

  • A registration-state of “registered”.

The following states are defined:

Value | Comment
Unregistered | The application is not currently registered to an IMS Server.
Unregistering | The application is performing de-registration from an IMS Server.
Registering | The application is attempting registration to an IMS Server.
Registered | The application is currently registered to an IMS Server.

See Also


SessionStateEnum (Enumerated Type)

Enumerated Type: SessionStateEnum

public enum SessionStateEnum

{

Idle = 0,

Idle = 1,

Ringing = 2,

Active = 3,

LocalHold = 4,

RemoteHold = 5,

Transferring = 6,

Updating = 7,

}

Field Description

SessionStateEnum denotes the specific call-state associated with a particular participant on a conference-call.

Value | Comment
Idle | Denotes that a participant is in a call-idle state. (i.e. there is no participant associated with this participant-information entry).
Idle | The conference-server is currently attempting to INVITE the associated participant into a conference-call.
Ringing | The associated participant is dialling into the conference (and the associated conference-line is in the RINGING state).
Active | The associated participant is active on the conference-call.
LocalHold | The conference-server has placed the associated participant into a call-held state.
RemoteHold | The conference-server has placed the associated participant into a call-held state.
Transferring | The conference-server is currently transferring the associated participant to another target (note: this state is currently unused).
Updating | The call-line between the conference-server and the associated participant is currently being refreshed (ex: session-timer based re-INVITE).

See Also


Using the COM Interface (Conference-Server)

Last Updated: 2014-06-02

Scripting languages generally provide dynamic/runtime resolution of Type GUIDs, however some compiled languages more commonly require static-linking/association to the GUID values (for example MS VC++). For languages which require this kind of static-linking against a binary type-library (.tlb) file, as part of the application installation the associated tlb file is provided, along with an example .NET source-code extract of the class ProgIDs and GUID definitions, to aid in utilizing the COM-wrapper interface.

The files are provided in a “COM” directory in the “API Tools” sub-directory associated with the installation and comprise the following files:

  • [E6966B_AppDir]\API Tools\COM\confservercomm_comtypes.tlb

  • [E6966B_AppDir]\API Tools\COM\IDs\ConfServerComm_ComGuids.cs

  • [E6966B_AppDir]\API Tools\COM\IDs\ConfServerComm_ComProgIDs.cs

The tlb is also useful, even for developers utilizing dynamic/runtime GUID/ProgID mapping, as it is possible to use Windows-based utilities on the binary tlb file to discern API/interface details of the exported COM interfaces/members.

An example tool which can be used to inspect the tlb file is “OleView.Exe” which is provided as part of the freely available Windows SDK (and also implicitly provided as part of non-express versions of MS Visual Studio).

The design of the COM interface is such that there is a single top-level COM object which you should COM-initialize (as in via CoCreateInstance() and so forth). The top-level class implements the COM_GUID__IF_COM interface (WCF-equivalent interface: IComInterface).

Once this class has been COM-initialized, the API-accessors via this COM interface are almost identical to the .NET-managed interface definitions in terms of hierarchy.

For example, the top-level COM class (which is the only class that can be COM-instantiated directly without an error/exception being thrown in the managed runtime) provides various accessor methods which return references or pointers to implementations of sub-interfaces.

This top-level class is identified in COM by the PROGID value associated with: COM_PROGID__CLS_COM_API.

Top-Level COM Interface (as defined in VB.NET)

    ''' <summary>
    ''' Top-Level COM-accessible interface providing access to all sub-interfaces
    ''' of the application.
    ''' </summary>
    ''' <remarks></remarks>

    <ComVisible(True), Guid(ComGuids.COM_GUID__IF_ICOM)>
    <InterfaceType(ComInterfaceType.InterfaceIsDual)>
    Public Interface IComInterface
       Function Connection() As <MarshalAs(UnmanagedType.Interface)> IConnection
       Function Application() As <MarshalAs(UnmanagedType.Interface)> IApplication
       Function Configuration() As <MarshalAs(UnmanagedType.Interface)> IConfiguration
       Function Logging() As <MarshalAs(UnmanagedType.Interface)> ILogging
       Function Status() As <MarshalAs(UnmanagedType.Interface)> IStatus
       Function CallControl() As <MarshalAs(UnmanagedType.Interface)> ICallControl

    End Interface

All of the sub-interfaces returned by the method calls in the top-level COM interface (IConnection, IApplication, and so forth) are exact COM-based equivalent class re-definitions of the WCF-based equivalents.

The native .NET/WCF interfaces or classes are defined as part of the “NET” namespace within the confserver-communicator .NET project, whereas the COM-based classes are defined as part of the “COM” namespace in the .NET project as outlined in the table below:

Namespace | Namespace-purpose in the Server-Communicator project
NET | .NET/WCF-based types, interfaces and classes
COM | COM-based types, interfaces and classes

The confserver-communicator DLL is (purposefully) not dotfuscated, to enable you to have the opportunity to run a reflection tool (such as .NET Reflector) in order to get additional detailed information regarding data-types, interfaces and classes that belong to the COM namespace and have been made COM-visible.

See Also

COM Wrapper

COM Type/Class Identifiers (Conference-Server)

Example Code Using COM Interface (Server)

Using the COM Interface (Server)

Example Code Using COM Interface (Client)

COM Type/Class Identifiers (Client)


COM Type/Class Identifiers (Conference-Server)

Last Updated: 2014-06-02

The identifiers outlined in this section describe a mapping between a COM-based GUID/PROGID identifier-variable (as defined in the sample code files outlined in Using the COM Interface (Conference-Server) and the equivalent WCF-based type. The associated GUID/PROG value (as registered in the Windows Registry) can be found in the “ComGuids” and “ComProgIDs” source-files provided with the application installation, and these values are used to uniquely identify COM objects/types that are registered to the Windows OS.

Mappings:

  • Enum_GUID_Mappings

  • Interface_GUID_Mappings

Enum GUID Mappings

ClientComm_ComGuid.vb variable-name | Equivalent WCF Type
COM_GUID__ENUM_IMS_CS_TRANSPORT_TYPE | ProtocolType
COM_GUID__ENUM_IMS_CS_ACTIVATION_STATE | AgSipConfActivationState
COM_GUID__ENUM_IMS_CS_CALL_STATE | AgSipConfCallState
COM_GUID__ENUM_IMS_CS_REG_STATE | AgSipConfRegState

Interface GUID Mappings

ClientComm_ComGuid.vb variable-name | Equivalent WCF Type
COM_GUID_IF_ICOM | IComInterface
COM_GUID_IF_ICONNECTION | IConnection
COM_GUID_IF_IAPPLICATION | IApplication
COM_GUID_IF_ICONFIGURATION | IConfiguration
COM_GUID_IF_ILOGGING | ILogging
COM_GUID_IF_ISTATUS | IStatus
COM_GUID_IF_ICALLCONTROL | ICallControll

Class GUID and ProgID Mappings

Since the Class GUID and ProgID values are used to map to a specific implementation of a COM-visible class (and therefore correlate to an externally-visible .NET class implementation), the GUID and ProgID mappings are not outlined here. They are implemented as opposed to having defined details that can be stated.

However, it should be noted here that these ID mappings are provided in the files available to help you use the COM interface. These files are described in the Using the COM Interface (Conference-Server) topic and their directory locations are shown here.

See Also

COM Wrapper

COM Type/Class Identifiers (Conference-Server)

Example Code Using COM Interface (Server)

COM Type/Class Identifiers (Server)

Example Code Using COM Interface (Client)

COM Type/Class Identifiers (Client)


Legacy 3GPP SMS Interworking

Last Updated: 2014-06-02

The topic provides directions on using Control-Plane Filtering in conjunction with Custom Error Responses to creating custom error responses with the Filtering Configuration user interface in the IMS-SIP Server application.

Legacy 3GPP SMS Interworking overview

The 3GPP specifications (3GPP TS 23.204, 24.341) outline the general architecture and mechanisms involved in interworking of cellular-based 3GPP SMS over IP-based networks (including IMS).

Essentially the legacy SMS content (encoded within TP and RP layer PDUs) are carried over IMS via encapsulation within SIP MESSAGE primitives.

One part of the interworking involves correlating subscriber identities between the cellular/legacy domain (utilizing MSISDNs) and the IMS domain (utilizing IMS-based URIs), and is the main part of configuration that is required in the Agilent applications to allow testing of 3GPP SMS transfer.

Within the Agilent solution, the you must correctly configure the Agilent (and third-party) Clients, and the Agilent IMS Server appropriately to facilitate correct interworking. For configuration details, refer to the following Agilent_IMS_Server_configuration and Agilent_IMS_Client_configuration descriptions.

Agilent IMS Server configuration

Subscriber-Data mappings (URI <> MSISDN):

The Agilent IMS Server must be configured with information to facilitate the mapping between MSISDN and SIP-URI addressing of UEs utilizing 3GPP SMS capability.

The way in which this is achieved is through the Subscriber-Data profiles.

Subscriber-Data is available via the following top-level menus in the IMS Server application:

This menu option provides access to the Subscriber-Data Manager, which allows the additional/removal and modification of individual subscriber-data profiles, via the following GUI dialog example:

As an example, assume we have a test UE which utilizes an UICC (with ISIM) that contains the following parameters:

  • MSISDN: 07976822024

  • IMS URI: “sip:ue@test.3gpp.com“

To add a subscription-data profile for this user into the server:

    1. First we add a new subscriber-data record (which is auto-populated with default values)

    2. Then, we modify the new record accordingly.

To perform step (1), we can simply click “Add” in the “Subscriber Data Config” GUI dialog which would result in something like the following:

Then, to perform step (2), the new Subscriber entry can be double-clicked, or it can be selected and the “Edit” button can be clicked. Doing either of these will result in the “Subscriber Data Property Editor” being displayed, similar to below:

To facilitate 3GPP SMS, we must populate the following entries in the “Identity” category of the subscriber data:

  • Asserted User ID

  • MSISDN

The Asserted-User ID should be configured to the IMS SIP-URI identity that the UE uses when it performs IMS registration (in our example this is “sip:ue@test.3gpp.com“).

The MSISDN must be provided to perform interworking with the legacy SMS domain, and should be a unique number associated with subscriber, in our example the UICC uses the following MSISDN: 07976822024.

The modified subscriber-data would therefore look like:

The subscriber-profile changes are committed once the “OK” button is pressed.

To facilitate SMS transfer between any two clients, the Agilent IMS Server application must have validly configured subscriber-profiles (as per the above directions) for both IMS clients (i.e. have valid identity mappings between URI<->MSISDN), otherwise SMS transfer will be unsuccessful.

SMSC Identity:

In addition to the subscriber-profile data, the user must also configure the SMSC identity parameters within the Agilent IMS Server application.

These can be found under “Configuration -> General Configuration" then click the SMSC Config”, and a GUI dialog similar to the following is provided:

Agilent IMS Client configuration

SMSC Identity:

From the IMS Client side, the Client must be configured with the MSISDN (legacy address) and PSI (IMS-based address) of the Short-Message Service Centre (SMSC).

The values configured must be consistent with those used in the Agilent Server application for the SMSC Identity.

These settings are highlighted in the example below:

See Also

Custom SIP Error Responses

How to Create Custom Error Responses


Troubleshooting

Last Updated: 2014-06-02

This topic contains troubleshooting information on common issues that are encountered while using the IMS-SIP Emulator Software and suggestions for troubleshooting them.

Issues

Registration

I am having trouble registering the client with the server.

  • Verify that the connection parameters specified in the Connection section of the Configuration tab are correct (for example: server address and port)

  • The IMS Server application is running correctly and the Transmission_Network_Interface configured on the Server is associated with the Reception_IP_Addresses and SIP_Port in the General Configuration dialog (accessible by selecting the Configuration->General Configuration menu.

  • No firewall or network security software is blocking traffic over any address and port combination that is required.

For registration problems, it is recommended to disable Authentication in the Server and enable Call Flow Logging for diagnostic purposes.

I see an error stating ‘Could not establish Security Association’

or

I see a SIP message stating ‘500 Internal Server Error’

If the error message Could not establish Security Association appears on the Errors tab and/or if in the Call Flow Log a 500 Internal Server Error appears in response to a REGISTER message then you should ensure the application is restarted with Administrator rights.

To run with Administrator rights, either right click on the application icon and then select Run as administrator, or right click on the icon and select Properties, then select the Compatibility tab then select the check box Run this program as an administrator.

API

I can’t control the Server / Conference Server / Client via the remote API

If an error message, similar to the following, appears on the ‘Errors’ tab, you should ensure that the application is restarted with Administrator rights.

Error Message:

UIMisc.SetWCFPortDelMarshal: HTTP could not register URL http://+:8240/Agilent/ImsSip/Server/. Your process does not have access rights to this namespace (see http://go.microsoft.com/fwlink/?LinkId=70353 for details).

To run with Administrator rights, either right click on the application icon and then select Run as administrator, or right click on the icon and select Properties, then select the Compatibility tab then select the check box Run this program as an administrator.

Miscellaneous

I can't send a video file.

Ensure the video is encoded one of the following supported codecs: H.263, H.263+, H.264.

I can't send an audio file.

Ensure that the audio contained within the media file is encoded in 8-bit mono format and using one of the following sample rates: 8kHz, 16kHz or 32kHz.

The playback rate of audio sounds wrong when using "Play Local" or "Sent Test".

Ensure that the audio contained within the media file is encoded in 8-bit mono format and using one of the following sample rates: 8kHz, 16kHz or 32kHz.


Example Code Using COM Interface (Conference-Server)

S

Last Updated: 2014-06-02

This example provides the COM-based equivalent of the .NET WCF example.

The test code below performs the following:

  • Initializes various COM-visible interfaces/sub-interfaces.

  • Connects (via COM) to the WCF interface of a running server application

  • Reads the Server application version-number and displays in a Windows MessageBox

  • (After the MessageBox is closed), starts call-flow logging on the server

  • Changes the AlternateMessageResponse value to "Forbidden"

  • Reads the AddressOfRecordAll property and displays the first entry

    Note: If there are no clients registered to the server when this property is read, it will likely print a garbled string here. So, it is recommended that a client is registered to the server before running the compiled executable.

  • The sample test program then terminates.

Test Code Begins Here:

#include <stdio.h>

#include <stdlib.h>

#include <atlbase.h> // for USES_CONVERSION

// DEFINEs for the possible COM Type-Library (TLB) file info paths..

#define TLB_SRC_LOCAL 0

#define TLB_SRC_INSTALL_WIN7 1

#define TLB_SRC_INSTALL_WINXP 2

// change this and recompile when changing the path to the TLB...

#define TLB_SRC TLB_SRC_INSTALL_WIN7

#if (TLB_SRC == TLB_SRC_LOCAL)

#import "C:\TFSDevelopment\SwIFT\IMS-SIP\Server\Main\Development\ImsSipServerCommunicator\ImsSipSvrComm\bin\x86\Release\COM\servercomm_comtypes.tlb"

#elif (TLB_SRC == TLB_SRC_INSTALL_WIN7)

#import "C:\Program Files (x86)\Agilent\E6966B\API Tools\COM\servercomm_comtypes.tlb"

#else (TLB_SRC == TLB_SRC_INSTALL_WINXP)

#import "C:\Program Files\Agilent\E6966B\API Tools\COM\servercomm_comtypes.tlb"

#endif

using namespace Agilent_ImsSip_ServerComm;

IComInterface* comIF = NULL;

IServer* server = NULL;

IConnection* conn = NULL;

ILogging* logging = NULL;

IAlternateResponse *altresponse = NULL;

IClientControl *clientctrl = NULL;

ISignalingControl *signalingctrl = NULL;

ICallControl *callctrl = NULL;

// For Subscription and SubscriptionManager testing...

ISubscriptionManager *subManager = NULL;

ISubscription *subscription = NULL;

// For Filter-Mgr Testing...

IControlPlaneConfig *ctrlplaneConfig = NULL;

IUserPlaneConfig *userplaneConfig = NULL;

IControlPlaneFilterMgr *ctrlplaneFilterMgr = NULL;

IFilterMgr *ctrlplaneFilterMgrUAC = NULL;

IFilterMgr *ctrlplaneFilterMgrUAS = NULL;

IFilterMgr *userplaneFilterMgr = NULL;

/*********************************************************

* InitSubInterfaces()

*********************************************************/

void InitSubInterfaces()

{

HRESULT hr = 0;

printf ("Initing Sub Interfaces\n");

hr = comIF->raw_Connection(&conn);

if (! SUCCEEDED(hr) ) printf("failed to get conn interface!\n");

hr = comIF->raw_Server(&server);

if (! SUCCEEDED(hr) ) printf("failed to get server interface!\n");

hr = comIF->raw_Logging(&logging);

if (! SUCCEEDED(hr) ) printf("failed to get logging interface!\n");

hr = comIF->raw_AlternateResponse(&altresponse);

if (! SUCCEEDED(hr) )

printf("failed to get the alternate response interface!\n");

hr = comIF->raw_ClientControl(&clientctrl);

if (! SUCCEEDED(hr) ) printf("failed to get the client-control interface!\n");

hr = comIF->raw_SignalingControl(&signalingctrl);

if (! SUCCEEDED(hr) ) printf("failed to get the signaling-control interface!\n");

hr = comIF->raw_SubscriptionManager(&subManager);

if (! SUCCEEDED(hr) )

printf("failed to get the subscription-manager interface!\n");

hr = comIF->raw_CallControl(&callctrl);

if (! SUCCEEDED(hr) ) printf("failed to get the call-control interface!\n");

// filtering-interfaces

if (signalingctrl != NULL)

{

hr = signalingctrl->get_ControlPlaneConfig(&ctrlplaneConfig);

if (! SUCCEEDED(hr) )

printf("failed to get the control-plane-config interface!\n");

if(ctrlplaneConfig != NULL)

{

hr = ctrlplaneConfig->get_ControlPlaneFilterMgr(&ctrlplaneFilterMgr);

if (! SUCCEEDED(hr) )

printf("failed to get the (top) control-plane filter-mgr interface!\n");

if (ctrlplaneFilterMgr != NULL)

{

hr = ctrlplaneFilterMgr->get_FilterMgr_UAC(&ctrlplaneFilterMgrUAC);

if (! SUCCEEDED(hr) )

printf("failed to get the control-plane UAC filter-mgr!\n");

hr = ctrlplaneFilterMgr->get_FilterMgr_UAS(&ctrlplaneFilterMgrUAS);

if (! SUCCEEDED(hr) )

printf("failed to get the control-plane UAS filter-mgr!\n");

}

}

hr = signalingctrl->get_UserPlaneConfig(&userplaneConfig);

if (! SUCCEEDED(hr) ) printf("failed to get the user-plane-config interface!\n");

if (userplaneConfig != NULL)

{

hr = userplaneConfig->get_FilterMgr_UP(&userplaneFilterMgr);

if (! SUCCEEDED(hr) ) printf("failed to get the user-plane filter-mgr!\n");

}

}

printf ("Initing Sub Interfaces Complete!\n");

}

/*********************************************************

* GetErrorInfo()

*********************************************************/

void GetErrorInfo(bool showMsgBox)

{

HRESULT hr = 0;

USES_CONVERSION;

CComBSTR mystring;

hr = conn->get_ErrorInformation(&mystring);

if (SUCCEEDED(hr))

{

LPCSTR convertedStr = OLE2CT(mystring);

printf ("succeeded in getting ErrorInformation! (%s)\n", convertedStr);

if (showMsgBox)

MessageBox (NULL, convertedStr, TEXT("Message is..."), MB_OK);

}

else

printf ("failed to get ErrorInformation!\n");

}

/*********************************************************

* Test Subroutine definition section

*

* NOTE: The IConnection test routine should always be

* called before any others as this one connects

* via WCF to the server application...!

*********************************************************/

VARIANT_BOOL IConnection_Test(char *pIpAddressStr, int portNumber)

{

VARIANT_BOOL success = false;

HRESULT hr = 0;

CComBSTR comBStr;

if (conn != NULL)

{

GetErrorInfo(false);

printf("got a conn ptr!\n");

comBStr = pIpAddressStr;

hr = conn->raw_Initialize(comBStr, portNumber, &success);

if (SUCCEEDED(hr))

printf("succeeded in performing initialize!\n");

else

printf("failed to perform initialize()!\n");

GetErrorInfo(false);

}

return success;

}

VARIANT_BOOL IServer_Test()

{

USES_CONVERSION; // Provides OLE2CT definition etc..

VARIANT_BOOL success = false;

HRESULT hr = 0;

CComBSTR comBStr;

// IServer control

if (server != NULL)

{

printf("got a server ptr!\n");

hr = server->get_Version(&comBStr);

if (SUCCEEDED(hr))

{

printf("successfully read server version!\n");

MessageBox (NULL, OLE2CT(comBStr), TEXT("Message is..."), MB_OK);

}

else

printf("failed to read server version! (0x%08x)\n", hr);

success = SUCCEEDED(hr);

}

return success;

}

VARIANT_BOOL ILogging_Test()

{

VARIANT_BOOL success = false;

HRESULT hr = 0;

// ILogging control

if (logging != NULL)

{

printf("got a logging ptr!\n");

hr = logging->raw_StartCallFlow();

if (SUCCEEDED(hr))

printf("successfully started call-flow logging!\n");

else

printf("failed to start call-flow logging!\n");

success = SUCCEEDED(hr);

}

return success;

}

VARIANT_BOOL IAlternateResponse_Test()

{

VARIANT_BOOL success = false;

HRESULT hr = 0;

// IAlternateResponse control

if (altresponse != NULL)

{

enum AltRespMessageType blah;

printf("got an altresponse ptr!\n");

hr = altresponse->get_MessageResponse(&blah);

if (SUCCEEDED(hr))

{

printf("succeeded reading message-response. value = %d\n", blah);

blah = AltRespMessageType_Forbidden;

hr = altresponse->put_MessageResponse(blah);

if (SUCCEEDED(hr))

printf("succeeded modifying message-response!\n");

else

printf("failed to modify message-response!\n");

}

else

printf("failed to read message-response value!\n");

success = SUCCEEDED(hr);

}

return success;

}

VARIANT_BOOL IClientControl_Test()

{

USES_CONVERSION; // Provides OLE2CT definition etc..

VARIANT_BOOL success = false;

HRESULT hr = 0;

// IClientControl control

if (clientctrl != NULL)

{

SAFEARRAY *aorArray;

printf("got a client-control pts!\n");

hr = clientctrl->get_AddressOfRecordAll(&aorArray);

if (SUCCEEDED(hr))

{

int z;

long indices[1];

void *pv;

printf("succeeded reading AddressOfRecordAll Property: \n");

for(z=0; z< 1; z++)

{

indices[0] = z;

SafeArrayGetElement(aorArray,

indices,

&pv);

printf("%s", OLE2CT((LPCWSTR)pv));

}

printf("\n");

hr = SafeArrayDestroy(aorArray);

if (!SUCCEEDED(hr))

printf("failed to destroy safe-array!\n");

//MessageBox (NULL, OLE2CT((LPCWSTR)aorArray->pvData),

// TEXT("Message is..."), //MB_OK);

}

else

printf("failed to get AddressOfRecordAll property!\n");

success = SUCCEEDED(hr);

}

return success;

}

VARIANT_BOOL ISubscriptionManager_Test(bool useMessageBoxes)

{

// The procedure for this test routine is as follows...

// 1 - Add a new subscription for "sip:COM_testuser1@test.com"

// 2 - Duplicate this subscription to "sip:COM_duplicatedtestuser1@test.com"

// 3 - Remove the original subscription created in (1)

// 4 - Modify the duplicated subscription (from step (2))

// 5 - Remove the newly modified subscription..

//

// Intermediate message-boxes are optionally used to halt the application at

// each stage to allow the tester to manually confirm the changes in the

// server application...

USES_CONVERSION; // Provides OLE2CT definition etc..

VARIANT_BOOL success = false;

HRESULT hr = 0;

CComBSTR comBStr1;

CComBSTR comBStr2;

CComBSTR comBStr3;

char newAssertedIdStr[] = "sip:COM_testuser1@test.com";

char dupAssertedIdStr[] = "sip:COM_duplicatedtestuser1@test.com";

char modAssertedIdStr[] = "sip:COM_modifiedtestuser1@test.com";

ISubscription *pSubscription;

struct SupplementaryServiceStruct ssConfig;

SAFEARRAY *pAssociatedUserIdArray = NULL;

// ISubscriptionManager control

if (subManager != NULL)

{

printf("\n\nSUBSCRIPTION_MGR TEST....\n");

// 1 - Add a new subscription..

comBStr1 = newAssertedIdStr;

hr = subManager->raw_AddNewSubscription(comBStr1, &pSubscription);

if (SUCCEEDED(hr))

{

printf("successfully added new subscription!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was added okay...

MessageBox (NULL, "Please verify new subscription has been added!",

TEXT("Message is..."), MB_OK);

}

// 2 - Duplicate the subscription

comBStr2 = dupAssertedIdStr;

hr = subManager->raw_DuplicateExistingSubscription(comBStr1,

comBStr2,

&pSubscription);

if (SUCCEEDED(hr))

{

printf("successfully duplicated the subscription!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was

// duplicated okay...

MessageBox (NULL, "Please verify new subscription has been duplicated!",

TEXT("Message is..."), MB_OK);

}

// 3 - Remove the originally created subscription

hr = subManager->raw_RemoveSubscription(comBStr1, &success);

if (SUCCEEDED(hr))

{

printf("successfully removed original subscription!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was

// removed okay...

MessageBox (NULL,

"Please verify original subscription has been removed!",

TEXT("Message is..."), MB_OK);

}

// 4 - Modify the duplicated subscription

hr = subManager->raw_GetSubscriptionData(comBStr2, &pSubscription);

if (!pSubscription)

{

printf("Failed to retrieve subscription data for duplicated user!\n");

return false;

}

comBStr3 = modAssertedIdStr;

// configure the supplementary-service data that we wish to associate with

// our changed subscription-data (and commit back into the subscriber

// database)

ssConfig.OipConfig.Active = 0;

ssConfig.OirConfig.Active = 1;

ssConfig.OirConfig.Mode = SSEnum_IDRestrictionMode_Permanent;

ssConfig.OirConfig.TemporaryMode =

SSEnum_IDRestrictionTempMode_PresRestricted;

ssConfig.OirConfig.RestrictionType =

SSEnum_IDRestrictionType_RestrictAllPrivateHeaderInfo;

ssConfig.TipConfig.Active = 0;

ssConfig.TirConfig.Active = 1;

ssConfig.TirConfig.Mode = SSEnum_IDRestrictionMode_Permanent;

ssConfig.TirConfig.TemporaryMode =

SSEnum_IDRestrictionTempMode_PresRestricted;

// hacky compound-statement (curly-braced) for allocating and

// populating the SafeArray for the associatedUserIdList....

{

char *associatedIdStrs[] = { "deeble", "feeble", "keeble", "weeble",

"neeble", "jeeble", "reeble", "peeble",

"zeeble", "mcNeeble" };

int nDims = 1;

int nElems = 10;

long indices[1];

void *pv;

indices[0] = nElems;

pAssociatedUserIdArray = SafeArrayCreateVector(VT_BSTR, 0, nElems);

for (int i=0; i<nElems; i++)

{

indices[0] = i;

SafeArrayPutElement (pAssociatedUserIdArray, indices,

A2BSTR(associatedIdStrs[i]));

}

}

// copy the various modified properties into our ISubscription

// object so that the changed-object is ready to be applied back

// into the subscriber database...

hr = pSubscription->put_AssertedId(comBStr3);

hr = pSubscription->put_AssociatedUserIdList( pAssociatedUserIdArray );

hr = pSubscription->put_SuppServiceConfig(ssConfig);

// apply/commit the changed subscription object back into

// the subscriber-database

hr = subManager->raw_ApplySubscriptionChanges(comBStr2, pSubscription,

&success);

SafeArrayDestroy(pAssociatedUserIdArray);

if (SUCCEEDED(hr) && success)

{

printf("successfully modified the subscription!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user

// was removed okay...

MessageBox (NULL, "Please verify duped subscription has been modded!",

TEXT("Message is..."), MB_OK);

}

// 5 - Remove the newly modified subscription...

hr = subManager->raw_RemoveSubscription(comBStr3, &success);

if (SUCCEEDED(hr) && success)

{

printf("successfully removed the modified subscription!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the

// user was removed okay...

MessageBox (NULL, "Please verify modified subscription has " \

"been removed!",

TEXT("Message is..."), MB_OK);

}

}

else

printf("failed to remove the modified subscription!\n");

}

else

printf("failed to modify subscription!\n");

}

else

printf("failed to remove original subscription!\n");

}

else

printf("failed to duplicate subscription!\n");

}

else

printf("failed to add new subscription!\n");

success = SUCCEEDED(hr);

}

return success;

}

VARIANT_BOOL ICallControl_Test(bool useMessageBoxes)

{

// The procedure for this test routine is as follows...

// 1 - Query and obtain a snapshot of the current user-plane media-core statistics

// (and other call-session data)

// 2 - Reset all user-plane/call-session data statistics.

//

// Intermediate message-boxes are optionally used to halt the application at

// each stage to allow the tester to manually confirm the changes in the

// server application...

USES_CONVERSION; // Provides OLE2CT definition etc..

VARIANT_BOOL success = false;

HRESULT hr = 0;

CComBSTR comBStr1;

CComBSTR comBStr2;

CComBSTR comBStr3;

SAFEARRAY *pSessionDataSnapshotArray = NULL;

// Filtering-core testing

printf("\nCALL_CONTROL TEST....\n");

if (callctrl != NULL)

{

if(useMessageBoxes)

{

// Display message-box prompting user to verify the user was removed okay...

MessageBox (NULL, "Please ensure that the user-plane media proxy capability is"\

" enabled in the Server and an IMS call is established"\

" between two clients!",

TEXT("Message is..."), MB_OK);

}

// 1 - Query/obtain session-data snapshot

hr = callctrl->raw_GetSessionDataSnapshot(&pSessionDataSnapshotArray);

if(SUCCEEDED(hr))

{

int i;

long numElems;

longindices[1];

ICallData *pCallData;

printf("successfully retrieved the session-stats snapshot.\n");

// get the number of elements (i.e. ICallData elements)

hr = SafeArrayGetUBound(pSessionDataSnapshotArray, 0, &numElems);

printf("numSessionsInSnapshotData = %d\n\n", numElems);

// loop through each element printing some info from each entry

for (i=0; i<numElems; i++)

{

indices[0] = i;

hr = SafeArrayGetElement(pSessionDataSnapshotArray, indices,

(void *) &pCallData);

if ( SUCCEEDED(hr))

{

hr = pCallData->get_OriginatingUri(&comBStr1);

hr = pCallData->get_TerminatingUri(&comBStr2);

hr = pCallData->get_CallID(&comBStr3);

printf("session-data:\n\t[orig-uri: %s],\n\t[term-uri: %s],\n\t[call-id: %s]\n",

OLE2CT((LPCWSTR)comBStr1),

OLE2CT((LPCWSTR)comBStr2),

OLE2CT((LPCWSTR)comBStr3));

}

else

printf("failed to get element-data from session-data snapshot!\n");

}

// release the resources allocated to the session-data snapshot SafeArray.

SafeArrayDestroy(pSessionDataSnapshotArray);

}

else

printf("failed to retrieve a call-control session-data snapshot!\n");

// 2 - Reset all user-plane/call-session data statistics.

hr = callctrl->raw_ResetAllSessionDataStatistics();

if(SUCCEEDED(hr))

{

printf("successfully reset/cleared the session-data stats.\n");

if(useMessageBoxes)

{

// Display message-box prompting user to verify the user was removed okay...

MessageBox (NULL, "Please verify that the UP session-stats have been reset!",

TEXT("Message is..."), MB_OK);

}

}

else

printf("failed to reset/clear session-data statistics!\n");

}

else

printf("No Call-Control interface is available for performing testing.\n");

return success;

}

VARIANT_BOOL FilteringCore_Test(bool useMessageBoxes)

{

// The procedure for this test routine is as follows...

// 1 - Add a control-plane UAC filter rule:

// "from: FROMUAC, request-uri: REQUAC, request=REGISTER, action=discard"

// 2 - Add a control-plane UAS filter rule:

// "from: FROMUAS, request-uri: REQUAS, responses=200 OK, action=delay:50ms"

// 3 - Add a user-plane filter-rule:

// "from: FROMUP, request-uri: REQUP, prot=rtcp, direction=rx, action=none"

// 4 - Get Trigger-Count for user-plane rule

// 5 - Remove all rules in steps 1-3

//

// Intermediate message-boxes are optionally used to halt the application at

// each stage to allow the tester to manually confirm the changes in the

// server application...

USES_CONVERSION; // Provides OLE2CT definition etc..

VARIANT_BOOL success = false;

HRESULT hr = 0;

long ruleId;

longtriggerCount;

CComBSTR comBStr1;

CComBSTR comBStr2;

CComBSTR comBStr3;

#define CRLF "\r\n"

char ctrlplaneUACRuleStr[] = "from-uri = FROMUAC" CRLF "request-uri = REQUAC" CRLF \

"request = REGISTER" CRLF CRLF "action = discard" CRLF;

char ctrlplaneUASRuleStr[] = "from-uri = FROMUAS" CRLF "request-uri = REQUAS" CRLF \

"response = 200 OK" CRLF CRLF "action = delay:50ms" CRLF;

char userplaneRuleStr[] = "from-uri = FROMUP" CRLF "request-uri = REQUP" CRLF \

"protocol = rtcp" CRLF "direction = rx" CRLF CRLF \

"action = none" CRLF;

// Filtering-core testing

printf("\nFILTERING_CORE TEST....\n");

// 1 - Add a control-plane UAC filter rule

if (ctrlplaneFilterMgrUAC != NULL)

{

comBStr1 = ctrlplaneUACRuleStr;

hr = ctrlplaneFilterMgrUAC->raw_AddFilterRule(comBStr1, &ruleId);

if (SUCCEEDED(hr))

{

printf("successfully added control-plane UAC filter rule!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was added okay...

MessageBox (NULL, "Please verify new CP UAC filter rule has been added!",

TEXT("Message is..."), MB_OK);

}

}

else

printf("failed to add control-plane UAC filter rule!\n");

}

else

printf ("No control-plane UAC filter interface available!");

// 2 - Add a control-plane UAS filter rule

if (ctrlplaneFilterMgrUAS != NULL)

{

comBStr2 = ctrlplaneUASRuleStr;

hr = ctrlplaneFilterMgrUAS->raw_AddFilterRule(comBStr2, &ruleId);

if (SUCCEEDED(hr))

{

printf("successfully added control-plane UAS filter rule!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was added okay...

MessageBox (NULL, "Please verify new CP UAS filter rule has been added!",

TEXT("Message is..."), MB_OK);

}

}

else

printf("failed to add control-plane UAS filter rule!\n");

}

else

printf ("No control-plane UAS filter interface available!");

// 3 - Add a user-plane filter rule

if (userplaneFilterMgr != NULL)

{

comBStr3 = userplaneRuleStr;

hr = userplaneFilterMgr->raw_AddFilterRule(comBStr3, &ruleId);

if (SUCCEEDED(hr))

{

printf("successfully added user-plane filter rule!\n");

if (useMessageBoxes)

{

// Display message-box prompting user to verify the user was added okay...

MessageBox (NULL, "Please verify new UP filter rule has been added!",

TEXT("Message is..."), MB_OK);

}

// 4 - Get Trigger-Count for user-plane rule

hr = userplaneFilterMgr->raw_GetTriggerCounterById(ruleId, &triggerCount);

if (SUCCEEDED(hr))

{

printf("successfully read user-plane trigger-count (%d)" \

"for filter-rule (ID: %d)\n", triggerCount, ruleId);

}

else

printf("failed to retrieve trigger-count for filter-rule (ID: %d)\n",

ruleId);

}

else

printf("failed to add user-plane filter rule!\n");

}

else

printf ("No user-plane filter interface available!");

// 5 - Remove all rules in steps 1-3

if(ctrlplaneFilterMgrUAC != NULL)

{

hr = ctrlplaneFilterMgrUAC->raw_RemoveAllFilterRules();

if (SUCCEEDED(hr))

printf("successfully removed all control-plane UAC filter-rules.\n");

else

printf("failed to remove control-plane UAC filter-rules.\n");

}

if(ctrlplaneFilterMgrUAS != NULL)

{

hr = ctrlplaneFilterMgrUAS->raw_RemoveAllFilterRules();

if (SUCCEEDED(hr))

printf("successfully removed all control-plane UAS filter-rules.\n");

else

printf("failed to remove control-plane UAS filter-rules.\n");

}

if(userplaneFilterMgr != NULL)

{

hr = userplaneFilterMgr->raw_RemoveAllFilterRules();

if (SUCCEEDED(hr))

printf("successfully removed all user-plane filter-rules.\n");

else

printf("failed to remove user-plane filter-rules.\n");

}

if(useMessageBoxes)

{

// Display message-box prompting user to verify the user was added okay...

MessageBox (NULL, "Please verify that the control-plane UAC, UAS and " \

"also user-plane rules have been removed!",

TEXT("Message is..."), MB_OK);

}

// I know that this only considers (and returns) the status of the

// last performed COM operation.. but this is only a sample..

// there's enough printf's and message-boxes to help navigate even the most

// weary of travellers..

success = SUCCEEDED(hr);

returnsuccess;

}

/*********************************************************

* Main Routine

*********************************************************/

int main(int argc, char *argv[])

{

char *ip_address_string_ptr;

char *port_num_string_ptr;

int portNumber;

HRESULT hr = 0;

VARIANT_BOOL success = false;

CLSID cls;

// Process the command-line params

if (argc != 3)

{

printf("\n\tUsage - comtest.exe <ip_address_string> <port_number>\n");

return 1;

}

ip_address_string_ptr = argv[1];

port_num_string_ptr = argv[2];

portNumber = atoi(port_num_string_ptr);

// do the COM testing...

hr = CLSIDFromProgID (L"Agilent.E6966B.ImsSipServer.ComAPI", &cls);

hr = CoInitialize(NULL);

if (! SUCCEEDED(hr))

{

printf("failed to CoInitialize()!\n");

return 0;

}

if (SUCCEEDED(hr))

{

hr = CoCreateInstance (cls, NULL, CLSCTX_INPROC_SERVER,

__uuidof(IComInterface), (void **) &comIF);

if (SUCCEEDED(hr))

{

CComBSTR mystring;

// Sub-interfaces *MUST* be initialized prior to calling

// any interface test-functions

InitSubInterfaces();

// IConnection testing (and initial WCF-based connectivity!)

success = IConnection_Test(ip_address_string_ptr, portNumber);

// IServer testing

success = IServer_Test();

// ILogging testing

success = ILogging_Test();

// IAlternateResponse testing

success = IAlternateResponse_Test();

// IClientControl testing

success = IClientControl_Test();

// ISubscriptionManager testing

ISubscriptionManager_Test(true);

// ICallControl testing

ICallControl_Test(true);

// Filtering-Core testing (control-plane UAC, UAS and

// user-plane filter-managers)..

FilteringCore_Test(true);

comIF->Release();

}

else

printf("Failed to create IComInterface! (0x%08x)\n", hr);

}

else

printf("Failed to find CLSID!\n");

CoUninitialize();

if (! SUCCEEDED(hr))

{

printf("failed to CoUninitialize()!\n");

return 0;

}

else

printf ("succeeding in performing CoUninitialize()!\n");

return 0;

}

See Also

COM Wrapper

Using the COM Interface (Server)

COM Type/Class Identifiers (Server)

Using the COM Interface (Client)

Example Code Using COM Interface (Client)

COM Type/Class Identifiers (Client)


Alphabetical List of Structures (Conference-Server)

Last Updated: 2014-06-02

  • ConfParticipantInfoStruct

See Also

Alphabetical List of Methods (Conference-Server)

Interfaces by Category (Conference-Server)

Reference of Enumerated Types (Conference-Server)


Property: Enable

Property Enable enables or disables Authentication. Authentication parameter configuration must be performed prior to enabling Authentication (see related Authentication API methods). Upon receiving a REGISTRATION method from a DUT/UE SIP Client, the SIP Server responds with a 401 AUTHENTICATION CHALLENGE message. The DUT/UE SIP Client then sends another REGISTRATION message containing the authentication response. The authentication response information is verified by the SIP Server service. If the verification is successful, the SIP Server responds with an OK message. If the authentication response fails, the SIP Server service responds with an UNAUTHORIZED message.


Property: AlgorithmType

The property AlgorithmType configures the SIP server to use one of three algorithms: AKAv1, AKAv2, or MD5 in all subsequent authentication checks.

If AlgorithmType is set to AKAv1, the following authentication configuration properties apply:

• ComparisonType

• Secret Key

• OP

• OpType

• RAND

• AMF

• ResetSQN (Method)

If AlgorithmType is set to AKAv2, the following authentication configuration properties apply:

• ComparisonType

• Secret Key

• OP

• OpType

• RAND

• AMF

• ResetSQN (Method)

If MD5 algorithm is set, the following authentication configuration properties apply:

• Realm

• ComparisonType

• UserName

• Password


TerminateSession_2 (Method)

Method: TerminateSession_2

bool TerminateSession_2 (ICallData sessionInfo);

Performs a reset of the Tx or Rx throughput counters associated with all sessions tracked by the Server.

Arguments

None

Returns

Possible return values are:

Returns | Description
List<ICallData> | A list of session-data structures which contain detailed information about the SIP session.

See Also

ICallControl


TerminateSession (Method)

Method: TerminateSession

bool TerminateSession (string originatingTag, string terminatingTag, string callId);

Performs a reset of the Tx or Rx throughput counters associated with all sessions tracked by the Server.

Arguments

None

Returns

None

See Also

ICallControl


FilterRuleTriggeredIndication (Method)

Method: FilterRuleTriggeredIndication

event: FilterRuleTriggeredIndication

event FilterRuleTriggeredIndicationDelegate FilterRuleTriggeredIndication;

An event/indication allowing an external application to associate a callback method with the same signature as FilterRuleTriggeredIndicationDelegate, which is defined as:

delegate void FilterRuleTriggeredIndication(

int id,

string timestamp,

int numDataStrings,

string[] dataStrings,

)

An associated callback is executed whenever an active/defined filter-rule has been triggered, if the filter-rule specified the “[indicate-when-triggered]” optional attribute.

Arguments

None

Returns

None

Notes

  • This event-mechanism only currently applies to control-plane filter-managers.

  • For an indication generated by a control-plane filter-manager, the callback parameters shall be populated as follows:

  • id = the unique-id associated with the filter-rule which triggered the indication.

  • timestamp = The string representation of the time at which the filter-rule was triggered.

  • numDataStrings = 2

  • dataStrings[0] = SIP Method name (ex: “REGISTER”)

  • dataStrings[1] = SIP Message content

  • If the message-content is larger than the WCF-interface maximum string length (approx 16Kb raw) the message-content shall be truncated.

  • The COM API interface uses a slightly different mechanism for associating a callback-handler and provides the following methods within the IFilterMgr interface:

  • void AddFilterRuleTriggeredIndicationHandler (IFilterRuleTriggeredIndicationEventHandler handler);

  • void RemoveFilterRuleTriggeredIndicationHandler(IFilterRuleTriggeredIndicationEventHandler handler);

  • Where, the IFilterRuleTriggeredIndicationEventHandler is defined as:

  • public interface IFilterRuleTriggeredIndicationEventHandler
    {
    void OnFilterRuleTriggeredIndication (int id, string timestamp,
    int numDataStrings, string[] dataStrings);
    }

See Also

IFilterMgr

IControlPlaneConfig

IControlPlaneFilterMgr


Interface: ILogging

Last Updated: 2014-06-02

This interface on the SIP Server enables access to the various logging modules that track all IMS-SIP operations. It is ideal for debugging, test verification and validation, and monitoring the state of SIP Server.

All messages/responses sent to and from each SIP Client registered with the SIP Server are monitored and logged at the Server. The logging Methods are displayed below. There are no Properties associated with these methods.

The various log modules (and API interface) tracked by the SIP server include:

  • Call_Flow_Log

  • Error_Log

  • Status_Log

  • Additional_Global_Logging_Methods

Call Flow Log – All messages that come into or go out of the SIP Server are logged. The entire SIP message is available through the SIP Server API. Detail logging methods are:

  • StartCallFlow

  • StopCallFlow

  • ClearCallFlow

  • SaveCallFlow

Error Log – Provides SIP Server error diagnostics.

  • ClearError

  • ReadError

  • SaveError

Status Log - Provides SIP Server state information and general information

  • ClearStatus

  • ReadStatus

  • SaveStatus

Additional Global Logging Methods

  • ClearAll


MwiMessageInfoStruct

Structure: MwiMessageInfoStruct

Last Updated: 2014-06-02

This structure, available in the Server API, encapsulates the information/fields associated with a single (simulated) message which is waiting/deposited (or shall be deposited) in a specific message-account.

Properties:

Property | Action | Type | Description
From | [set/get] | string | The originator of the message (ex: “bill@agilent.com”).
To | [set/get] | string | The target of the message (ex: “dave@agilent.com”)
Subject | [set/get] | string | The subject-line of the message (ex: “working from home today”)
Date | [set/get] | string | The time-stamp associated with the message (ex: “Wed, 23 Apr 2014 13:00:00 GMT”) [For additional information, see notes below.].
Priority | [set/get] | MessagePriorityEnum | The priority of the message.
MsgId | [set/get] | string | A unique-identifier associated with this message instance. [For additional information, see notes below].
MessageContext | [set/get] | MessageContextEnum | The message-context associated with this message instance.

Notes

  • The “Date” field must be formatted/specified as per the date-time field in section 3.3 of RFC 2822 [10], with the exception that folding-whitespace is not supported here. This “Date” field constitutes the date-time part of orig-date (outlined in section 3.6.1 of RFC 2822) associated with the message.

  • The only exception to this is when the “Date” value has been specified as a null-string, in which case the Server shall automatically populate the Date field with the local server-time (for the case where the message-entry is being added/modified in a message-box using the GUI).

  • The “MsgId” field can be specified as a null-string when performing an add/set action on a specific mailbox. In such a case, the server shall automatically generate a random message-identifier and associate it in the structure.

Fields

None

See Also


IpAddrInfoStruct

Structure: IpAddrInfoStruct

Last Updated: 2014-06-02

This structure, available in the Server API, encapsulates IP-address information related to the local configuration of the system on which the application is executing.

Properties:

Property | Action | Type | Description
Address | [get] | string | The string-representation of an IP-address assigned/allocated on the local system. (for example: “192.168.1.230”) Read-only property.
AssociatedInterfaceName | [get] | string | The interface-name (as managed by the underlying operating system) of the network adapter to which the value of the “Address” property is associated on the local system. (for example: “Local Area Connection”) Read-only property.

Fields

None


Interface: ISmscConfig

S

Last Updated: 2014-06-02

This interface provides access to the configuration/parameters associated with the Short-Message Service-Centre (SMSC) associated with legacy 3GPP binary SMS transfer.

Methods

None

Properties

Property | Action | Type | Description
SmscMsisdn | [get/set] | String (digit-string) | Specifies the MSISDN number (digit-string) which identifies the SMSC. Example: “1234512345”
SmscPsi | [get/set] | String (SIP-URI) | Specifies the SIP-URI associated with the Public Service Identity (PSI) of the SMSC. Example: “sip:sc@agilent.com” .

See Also

IMessageAccountMgr


PRACK Support

Last Updated: 2014-06-02

The Provisional Response ACKnowledgement enables provisional responses to be explicitly acknowledged during session-establishment procedures, to process the various states of the transaction. The current uses of provisional responses are limited to initial session-establishment using the INVITE method. The behavior/procedures of a SIP client during transactions which utilize PRACK capabilities is outlined below .

UAC PRACK Support

UAC PRACK specifies the role (throughout the entire session-establishment procedure) associated with the client that sends the initial session-establishment request (SIP INVITE).

The UAC is responsible for mandating the use of, and/or indicating support for PRACK procedures, and also for providing PRACKs for successfully received provisional-responses which invoke/utilize the use of PRACK.

The table below shows client-capable configurations:

Configuration | PRACK support indicated1 | PRACK procedures mandated2
A3 | No | No
B | Yes | No
C | Yes | Yes

Notes:

  1. PRACK support is indicated by including “100rel” in the “Supported” header of the session-establishment (INVITE) request.
  2. Mandating the support of PRACK procedures is achieved by including “100rel” in the “Requires” header of the session-establishment (INVITE) request.
  3. In this configuration, if the UAC receives provisional-responses for which PRACK invocation is attempted, the UAC shall not invoke PRACK handling.


Notices

Last Updated: 2014-06-02

Copyright © Agilent Technologies, Inc. 2012

No part of this Help file may be reproduced in any form or by any means (including electronic storage and retrieval or translation into a foreign language) without prior agreement and written consent from Agilent Technologies, Inc. as governed by United States and international copyright laws.

Warranty

The material contained in this document is provided “as is,” and is subject to being changed, without notice, in future editions. Further, to the maximum extent permitted by applicable law, Agilent disclaims all warranties, either express or implied, with regard to this manual and any information contained herein, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. Agilent shall not be liable for errors or for incidental or consequential damages in connection with the furnishing, use, or performance of this document or of any information contained herein. Should Agilent and the user have a separate written agreement with warranty terms covering the material in this document that conflict with these terms, the warranty terms in the separate agreement shall control.

Technology Licenses

The hardware and/or software described in this document are furnished under a license and may be used or copied only in accordance with the terms of such license.

Restricted Rights Legend

If software is for use in the performance of a U.S. Government prime contract or subcontract, Software is delivered and licensed as “Commercial computer software” as defined in DFAR 252.227-7014 (June 1995), or as a “commercial item” as defined in FAR 2.101(a) or as “Restricted computer software” as defined in FAR 52.227-19 (June 1987) or any equivalent agency regulation or contract clause. Use, duplication or disclosure of Software is subject to Agilent Technologies’ standard commercial license terms, and non-DOD Departments and Agencies of the U.S. Government will receive no greater than Restricted Rights as defined in FAR 52.227-19(c)(1-2) (June 1987). U.S. Government users will receive no greater than Limited Rights as defined in FAR 52.227-14 (June 1987) or DFAR 252.227-7015 (b)(2) (November 1995), as applicable in any technical data.

Acknowledgements

Microsoft® is a U.S. registered trademark of Microsoft Corporation

Windows® and MS Windows®, and MS Windows® 7 are U.S. registered trademarks of Microsoft Corporation.

Adobe® Acrobat ® are trademarks of Adobe Systems Incorporated.